How Omarchy Resolves CLI Commands to Binaries: Fast‑Path and Metadata Routing

Omarchy resolves spaced commands like omarchy theme set foo to executable binaries by joining arguments with hyphens, probing for files matching the omarchy-* pattern, and falling back to metadata‑driven route tables when necessary.

The omacom/omarchy repository implements a lightweight command‑line router that eliminates complex parsing by treating the filesystem as the source of truth. Instead of maintaining a central registry, the router discovers commands dynamically based on filenames and optional comment headers.

The File Naming Convention That Defines Routes

Every executable file in the bin/ directory that starts with omarchy- automatically registers one or more command routes. The router derives the group and name directly from the filename using a simple parsing rule:

• The characters after omarchy- are split at the first hyphen
• Everything before the first hyphen becomes the group
• Everything after becomes the name, with remaining hyphens converted to spaces

For example, bin/omarchy-theme-set registers the canonical route omarchy theme set because:

• Group: theme
• Name: set (derived from set)

The router also registers a filename route where every hyphen is replaced with a space, ensuring the textual command matches the binary exactly.

Fast‑Path Resolution: Hyphen‑Joined Binary Probing

When you run a command, the router in bin/omarchy first attempts fast‑path resolution to minimize overhead. This method joins the supplied arguments with hyphens and checks for a matching executable file without reading any metadata.

# Inside dispatch_fast_or_help()

binary="omarchy-$(join_words "-" "${args[@]:0:prefix_count}")"

If you execute omarchy theme set tokyo-night, the router performs these probes:

1. omarchy-theme-set-tokyo-night → not found
2. omarchy-theme-set → found (bin/omarchy-theme-set)

The router then executes the binary with the remaining arguments:

exec bin/omarchy-theme-set tokyo-night

This approach requires only a few stat calls and avoids parsing comment headers entirely.

Metadata‑Driven Fallback Routing

If the fast path fails to find a matching binary, the router loads command metadata from the first 80 lines of every omarchy-* script. According to the specification in agents/skills/command-metadata.md, developers can override routes, define aliases, hide commands from help output, or add descriptions using structured comments.

After parsing metadata from all binaries, the router builds a route table (ROUTE_TO_KEY) and performs a longest‑prefix lookup via resolve_route (lines 119‑127 in bin/omarchy). This allows commands to expose multiple aliases without creating separate files.

Dispatch Flow and Execution

The omarchy binary follows a strict dispatch sequence defined in bin/omarchy:

1. Direct route attempt – The resolve_direct_route function (lines 98‑104) checks for exact filename matches
2. Argument passing – If found, leftover arguments are passed directly to the binary via exec
3. Help interception – If --help or -h appears in the remaining arguments, the router loads metadata and displays usage information instead of executing the command
4. Metadata fallback – If the fast path fails, the full route table is consulted and the router either executes the correct binary or suggests "did you mean?" alternatives

Handling Arguments and Help Flags

When a user appends --help to any command, the router detects this before execution and renders formatted help text based on the binary's comment header metadata. This ensures consistent documentation without requiring separate man pages.

Example: Resolving omarchy theme set foo

Consider the complete resolution path for the command omarchy theme set foo:

• User input: Three arguments (theme, set, foo)
• Fast‑path probe: The router checks omarchy-theme-set-foo (does not exist), then omarchy-theme-set (exists at bin/omarchy-theme-set)
• Execution: The router calls exec bin/omarchy-theme-set foo, passing foo as an argument to the theme‑setting binary
• Implementation: The actual logic for setting themes resides in bin/omarchy-theme-set, whose metadata header defines the command summary, argument specifications, and examples

Summary

• Filename convention: Binaries starting with omarchy- automatically register routes based on hyphen positions
• Fast path: Arguments are joined with hyphens to probe for direct matches before loading metadata
• Metadata fallback: If filename probing fails, the router parses comment headers to build a route table supporting aliases and hidden commands
• Execution model: Found binaries are executed directly via exec with remaining arguments appended
• Help system: The router intercepts --help flags to display metadata rather than running the command

Frequently Asked Questions

How does Omarchy map spaced commands to binaries?

Omarchy replaces spaces with hyphens to construct filenames. The command omarchy theme set maps to bin/omarchy-theme-set by joining the arguments. The router probes progressively shorter hyphenated combinations until it finds an executable match.

What happens if no binary matches the command arguments?

If the fast‑path probe fails, the router loads metadata from all omarchy-* files, builds a route table, and performs a longest‑prefix lookup. If still unresolved, it displays a "did you mean?" suggestion list based on similar command names.

How can I add aliases or hide commands in Omarchy?

Add structured comment headers to your omarchy-* script within the first 80 lines. According to agents/skills/command-metadata.md, you can use keys like omarchy:alias to register alternate routes or omarchy:hidden to exclude the command from help listings.

Where is the route table stored in Omarchy?

There is no static registry file. The route table is computed dynamically at runtime by scanning the bin/ directory for omarchy-* executables and parsing their metadata headers. This auto‑discovery mechanism eliminates the need to update central configuration when adding new commands.

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