How Omarchy Parses Command Metadata: Understanding `#omarchy:summary` and `#omarchy:hidden`

The Omarchy CLI router treats executable scripts as self-describing binaries by scanning the first 80 lines for comments matching # omarchy:key=value, parsing them into an associative array that controls command visibility, documentation, and behavior.

Omarchy, the declarative Linux workstation framework from Basecamp, implements a self-documenting CLI architecture where command scripts carry their own metadata. The router located at bin/omarchy extracts configuration directly from script headers to build help menus, handle argument completion, and filter hidden commands without relying on external manifest files. Understanding this parsing mechanism allows developers to properly annotate custom commands for the Omarchy ecosystem.

How the Router Scans Command Scripts

When the Omarchy router initializes, it walks the bin/ directory and inspects every executable file to discover available commands. Rather than parsing entire files, the system samples only the header region to maximize startup performance.

For each file cmd_path, the router executes head -n 80 "$cmd_path" and pipes the result into a Bash while read -r line loop. This 80-line limit ensures rapid CLI initialization while accommodating substantial metadata blocks. Lines beyond this boundary are ignored entirely, even if they contain valid # omarchy: directives.

The Parsing Algorithm Step-by-Step

The extraction logic follows a precise sequence defined in the first 80 lines of bin/omarchy. Each line undergoes validation and transformation before populating the command's metadata registry.

1. Header capture: The router retrieves the first 80 lines using the head command.

2. Pattern validation: Each line is tested against the regex ^# omarchy:([A-Za-z_-]+)=(.*)$. Malformed lines are silently discarded.

3. Key isolation: Capture group 1 yields the metadata key (e.g., summary, hidden, requires-sudo).

4. Value extraction: Capture group 2 contains the raw value string.

5. Key normalization: Keys are lower-cased and hyphens converted to underscores, transforming requires-sudo into requires_sudo.

6. Type coercion: Values matching the literal strings true or false convert to Bash booleans; all other values are whitespace-trimmed and stored as literal strings.

7. Array population: Parsed pairs populate an associative array named meta (e.g., meta[summary], meta[hidden]).

8. Default fallback: Missing keys inherit inferred values, such as the filename for command names or empty strings for optional fields like summary.

Populating Help Documentation with #omarchy:summary

The summary metadata key provides the human-readable description displayed in omarchy help output and shell completion menus. When populated, meta[summary] overrides any auto-generated description, giving command authors precise control over user-facing documentation.

To add a summary to a custom command, include a comment line following the exact format:

#!/usr/bin/env bash

# omarchy:summary=Take a screenshot of the selected region

# omarchy:args=[smart|region|window|fullscreen]

# omarchy:examples=omarchy screenshot region | omarchy screenshot fullscreen

# Implementation follows...

According to the source code in bin/omarchy, these summaries feed directly into the GROUP_DESCRIPTIONS array that powers the interactive help system. The completion scripts located in default/bash/completions also reference this value when providing argument hints to the user.

Hiding Commands with #omarchy:hidden

Commands marked with # omarchy:hidden=true remain fully functional but disappear from default listings and help menus. The router checks meta[hidden] when assembling the command table, executing continue to skip entries where the value equals boolean true.

This mechanism suits utility scripts, internal debugging tools, or deprecated commands that must remain accessible without cluttering the primary interface. The command remains callable by its explicit name because the router still registers the binary path; only the listing behavior changes.

Implementation requires a single metadata line:

#!/usr/bin/env bash

# omarchy:summary=Internal debug utility for developers

# omarchy:hidden=true

# Debug implementation...

Even though this command executes normally when invoked directly (e.g., omarchy debug-helper), it will not appear in omarchy help or the auto-generated command table.

Advanced Metadata Configuration

Beyond basic visibility and descriptions, the parser supports additional keys documented in agents/skills/command-metadata.md. The requires-sudo key automatically adds privilege escalation hints to help output, while name and group override the default command categorization derived from filename prefixes.

A complete example demonstrating multiple metadata fields:

#!/usr/bin/env bash

# omarchy:name=system-reboot

# omarchy:group=system

# omarchy:summary=Reboot the machine safely

# omarchy:requires-sudo=true

# omarchy:hidden=false

# Reboot logic...

In this case, the router registers the command as system-reboot within the system group, displays the summary with a sudo warning, and includes it in standard listings. The parser normalizes requires-sudo to requires_sudo in the meta array, which the help generator checks to display privilege requirements.

Summary

• The Omarchy router scans the first 80 lines of each executable in bin/ to extract metadata comments using head -n 80.

• Comments must match the regex ^# omarchy:([A-Za-z_-]+)=(.*)$ to be recognized by the parser.

• Parsed values populate the meta associative array, with keys normalized to lowercase and underscores.

• The summary key drives help documentation and completion descriptions shown to users.

• The hidden key filters commands from listings while preserving executability via direct invocation.

• Boolean strings (true/false) convert automatically during parsing; other values remain literal strings.

• All parsing logic resides in bin/omarchy, with key specifications documented in agents/skills/command-metadata.md.

Frequently Asked Questions

How many lines does the Omarchy router scan for metadata?

The router examines only the first 80 lines of each executable script using head -n 80. This constraint balances comprehensive metadata support with startup performance, ensuring the CLI remains responsive even when numerous custom commands are present.

Can I use custom metadata keys beyond the standard set?

While the router accepts any key matching the # omarchy:key=value pattern and stores it in the meta associative array, only documented keys in agents/skills/command-metadata.md affect built-in router behavior. Custom keys are accessible to your scripts but will not alter the command listing, help output, or completion generation unless you modify the router itself.

What happens if a metadata line is malformed?

Lines that do not match the regex ^# omarchy:([A-Za-z_-]+)=(.*)$ are silently ignored during parsing. This includes comments with misspelled prefixes (e.g., # omachy:...), missing equals signs, or invalid characters in the key name. The router continues processing subsequent lines without throwing errors.

Where is the metadata parsing logic located in the source code?

The complete parsing implementation resides in the router script bin/omarchy, specifically within the first 80 lines where the "Command metadata" section handles the head extraction, regex matching, and associative array population. The supported keys and their semantics are documented in agents/skills/command-metadata.md.

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