Where Are Omarchy Group Descriptions Stored? A Deep Dive into the Core Dispatcher

Omarchy group descriptions are stored in the GROUP_DESCRIPTIONS associative array defined inside the bin/omarchy dispatcher script.

Omarchy organizes its CLI commands into logical groups like audio, theme, and update, each with a human-readable description. Understanding where these omarchy group descriptions live is essential for customizing the help interface or extending the framework. According to the omacom/omarchy source code, this metadata resides in a single Bash associative array within the core entry point.

The GROUP_DESCRIPTIONS Array in bin/omarchy

All group metadata is centralized in bin/omarchy, the main dispatcher script that routes subcommands to their respective handlers. Near the top of this file (starting around line 27), the script declares a Bash associative array named GROUP_DESCRIPTIONS that maps group names to their descriptive strings.

declare -A GROUP_DESCRIPTIONS

GROUP_DESCRIPTIONS[agent]="AI coding agent usage data"
GROUP_DESCRIPTIONS[ascii]="Text drawn as ASCII art"
GROUP_DESCRIPTIONS[audio]="Audio input and output controls"

# ... additional groups follow

This declarative approach keeps the metadata collocated with the command routing logic, making it straightforward to update descriptions without hunting through multiple configuration files.

How the Dispatcher Renders Group Help

When users invoke omarchy without arguments or pass the --help flag, the script calls the show_group_list() function to print a formatted table of available groups. This function iterates over the keys of GROUP_DESCRIPTIONS, sorts them alphabetically, and outputs aligned columns.

show_group_list() {
    local sorted_group=""
    printf '%s\n' "${!GROUP_DESCRIPTIONS[@]}" | sort | while IFS= read -r sorted_group; do
        [[ -n $sorted_group ]] || continue
        printf '  %-14s %s\n' "$sorted_group" "${GROUP_DESCRIPTIONS[$sorted_group]}"
    done
}

The function uses indirect expansion (${!GROUP_DESCRIPTIONS[@]}) to retrieve all group keys, pipes them through sort for consistent ordering, then formats each entry with a fixed-width column for the group name.

Modifying or Accessing Group Descriptions

Because GROUP_DESCRIPTIONS is a standard Bash associative array, you can manipulate it using standard shell syntax for sourcing or extension.

Adding a New Group Description

To register a description for a custom command group, append a new key-value pair to the array in bin/omarchy after the existing entries:

# In bin/omarchy, following the existing declarations:

GROUP_DESCRIPTIONS[mygroup]="My custom group for experimental commands"

Retrieving Descriptions Programmatically

External scripts can source the dispatcher to access the array directly:

#!/usr/bin/env bash
source "$OMARCHY_PATH/bin/omarchy"   # loads GROUP_DESCRIPTIONS into scope

echo "The description for 'theme' is: ${GROUP_DESCRIPTIONS[theme]}"

Displaying All Groups

You can reuse the built-in formatting function to output the complete group list exactly as the help command does:

#!/usr/bin/env bash
source "$OMARCHY_PATH/bin/omarchy"
show_group_list

Running this snippet produces output similar to:

  agent          AI coding agent usage data
  ascii          Text drawn as ASCII art
  audio          Audio input and output controls
  theme          Theme and appearance settings
  update         System update operations

Related Files and Architecture

While bin/omarchy holds the authoritative descriptions, several other files reference this metadata:

• docs/menu.md — Documents the JSON schema for menu entries that reference these groups
• agents/skills/command-metadata.md — Explains how command metadata, including group associations, is parsed from script comments

These files form a cohesive system where bin/omarchy serves as the single source of truth for group descriptions, while documentation and agent skills consume that metadata.

Summary

• Omarchy stores group descriptions in the GROUP_DESCRIPTIONS associative array inside bin/omarchy.
• The show_group_list() function reads this array to generate the help interface.
• Descriptions are defined as simple key-value pairs (GROUP_DESCRIPTIONS[groupname]="description").
• You can modify descriptions by editing bin/omarchy or source the script to access the array programmatically.

Frequently Asked Questions

Where exactly is the GROUP_DESCRIPTIONS array defined in the source code?

The array is defined near the top of bin/omarchy, starting at approximately line 27, immediately following the declare -A GROUP_DESCRIPTIONS initialization.

Can I modify group descriptions without editing the core script?

Currently, no. Because GROUP_DESCRIPTIONS is hardcoded in bin/omarchy, you must edit that file to change descriptions. There is no external configuration file or environment variable override for group metadata in the current implementation.

How does Omarchy sort the group list in the help output?

The show_group_list() function sorts the group names alphabetically using the sort command. It iterates over the array keys with ${!GROUP_DESCRIPTIONS[@]}, pipes them through sort, and then prints each description in that sorted order.

What happens if I add a group description but no corresponding commands?

The show_group_list() function will still display the group name and description in the help output. However, unless you also create command scripts that reference that group in their metadata, the group will appear empty when users try to list its specific commands.

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