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

> Discover where omarchy group descriptions are stored. This guide reveals the exact location within the core dispatcher script for easy access and management.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: deep-dive
- Published: 2026-09-04

---

**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.

```bash
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.

```bash
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:

```bash

# 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:

```bash
#!/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:

```bash
#!/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`](https://github.com/omacom/omarchy/blob/main/docs/menu.md)** — Documents the JSON schema for menu entries that reference these groups
- **[`agents/skills/command-metadata.md`](https://github.com/omacom/omarchy/blob/main/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.