How Command Groups Are Defined in Omarchy: The GROUP_DESCRIPTIONS Registry Explained

Command groups in Omarchy are defined via the GROUP_DESCRIPTIONS associative array in bin/omarchy, which maps group prefixes like capture and install to human-readable descriptions that drive the CLI's help output.

Omarchy organizes its user-facing commands into logical groups that share a common prefix, making the toolset intuitive and maintainable. According to the basecamp/omarchy source code, the authoritative registry for these groups lives in a central Bash associative array that powers both command routing and help generation. Understanding how command groups are defined in Omarchy is essential for contributors adding new functionality or customizing the interface.

The GROUP_DESCRIPTIONS Registry

At the heart of Omarchy's command organization is the GROUP_DESCRIPTIONS associative array defined in bin/omarchy (lines 27-91). This data structure maps short group identifiers—such as capture, install, and theme—to descriptive strings that appear when users invoke omarchy <group> or request top-level help.

Registry Structure and Location

The dispatcher script bin/omarchy serves as the single source of truth for group metadata. When you examine the source, you'll find the GROUP_DESCRIPTIONS declaration near the top of the file, establishing a contract between the CLI interface and its various subcommands. Each entry in this array follows the pattern:

GROUP_DESCRIPTIONS[group_key]="Human-readable description of the group"

This registry is consulted by the help printer (around line 510) to display a sorted list of available groups when users run omarchy help or invoke the binary without arguments.

File Naming Conventions and Routing

Individual commands follow a strict naming convention under the bin/ directory. Each executable must match the pattern bin/omarchy-<group>-<action>, where <group> corresponds to a key registered in the GROUP_DESCRIPTIONS array.

For example, omarchy-capture-record belongs to the capture group, while omarchy-install-package belongs to the install group. When the dispatcher parses arguments, it extracts the group token, looks up its description in the registry, and routes the call to the corresponding script.

Help Generation and User Experience

The GROUP_DESCRIPTIONS array directly powers the help system. As implemented in basecamp/omarchy, the help printer iterates through this associative array around line 510 in bin/omarchy to generate the categorized command listing. This ensures that users see consistent, up-to-date descriptions for every command group without manual updates to the help text logic.

Maintaining the Registry

The AGENTS.md documentation (line 38) explicitly requires contributors to keep the GROUP_DESCRIPTIONS array up-to-date whenever a new command prefix is added. This policy ensures the top-level help output remains accurate and that new functionality is immediately discoverable by users.

Hidden Commands

Not all commands appear in help listings. Developers can mark scripts as hidden by including the comment # omarchy:hidden=true in the source file. These commands remain routable by the dispatcher but are omitted from the GROUP_DESCRIPTIONS-driven help display, allowing for experimental or administrative functions that shouldn't clutter the standard interface.

Adding a New Command Group

To define a new command group in Omarchy, follow this implementation pattern:

# Step 1: Create the command script following the naming convention

# File: bin/omarchy-newgroup-action

#!/usr/bin/env bash

# ...implementation details...

# Step 2: Register the group in bin/omarchy (lines 27-91)

# Add to the GROUP_DESCRIPTIONS associative array:

GROUP_DESCRIPTIONS[newgroup]="Description of the new group functions"

# Step 3: Verify via help output

omarchy help

Key files involved in this process include:

• bin/omarchy — Central dispatcher that defines GROUP_DESCRIPTIONS and routes commands
• AGENTS.md — Developer guidance requiring registry maintenance
• bin/omarchy-<group>-* — Individual command scripts belonging to specific groups

Summary

• The GROUP_DESCRIPTIONS associative array in bin/omarchy serves as the authoritative registry for all command groups in the basecamp/omarchy repository.
• Group definitions appear at lines 27-91 and drive help output generation around line 510.
• Command scripts must follow the bin/omarchy-<group>-<action> naming pattern to be properly routed.
• The AGENTS.md file at line 38 requires updates to this registry whenever introducing new group prefixes.
• Hidden commands use # omarchy:hidden=true to exclude themselves from help listings while remaining callable.

Frequently Asked Questions

What file defines command groups in Omarchy?

Command groups are defined in the bin/omarchy dispatcher script through the GROUP_DESCRIPTIONS associative array located at lines 27-91. This Bash data structure maps group identifiers like capture and install to their human-readable descriptions, which the help printer references around line 510.

How do I add a new command group to Omarchy?

Create a script named bin/omarchy-<group>-<action> for your command, then add an entry to the GROUP_DESCRIPTIONS array in bin/omarchy following the existing pattern at lines 27-91. The AGENTS.md documentation at line 38 mandates this registry update to ensure the new group appears in the top-level help output.

Why isn't my new command showing up in the help output?

Verify that you have added the group identifier to the GROUP_DESCRIPTIONS array in bin/omarchy and confirm the script filename follows the omarchy-<group>-<action> convention. If the script contains # omarchy:hidden=true, it will be intentionally excluded from help listings while remaining fully functional.

Can I hide a command from the group listings while keeping it functional?

Yes. Add the comment # omarchy:hidden=true to the command script's source code. The dispatcher will still route calls to this script, but the help printer (around line 510) will exclude it from the visible group listings derived from GROUP_DESCRIPTIONS.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}