How Fast-Path Dispatch Works in the Omarchy CLI: A Two-Stage Routing Deep Dive

The Omarchy CLI uses a two-stage routing algorithm that probes hyphenated binary names via filesystem stat calls before falling back to metadata parsing, keeping typical command invocations fast even with hundreds of available commands.

The Omarchy CLI (omacom/omarchy) implements an elegant command router that transforms user-friendly spaced commands like omarchy theme set dark into direct executable lookups without parsing any metadata files. This fast-path dispatch mechanism minimizes latency for the common case while preserving flexibility for aliased or renamed commands.

The Two-Stage Routing Algorithm

The router in bin/omarchy follows a strict priority order: filesystem probes first, metadata parsing only when necessary.

Stage 1: Fast-Path Probe

The router constructs candidate binary names by progressively joining arguments with hyphens and checking for existence in the bin/ directory.

For the command omarchy theme set foo:

1. Probe bin/omarchy-theme-set-foo → if found, execute
2. Probe bin/omarchy-theme-set → if found, execute with leftover argument foo
3. Continue prefix truncation until match or exhaustion

This stage performs only stat syscalls—no file contents are read. According to the CLI router documentation (lines 53-60 of docs/cli-router.md), this design keeps the hot path "free of metadata overhead."

Stage 2: Fallback to Metadata

If no hyphenated binary exists, the router loads comment-based metadata from all binaries in bin/. It builds a complete route table and performs longest-prefix matching. This slower path supports:

• Commands renamed via metadata headers
• Aliases and deprecated command mappings
• Dynamic route customization without file renames

Fast-Path Dispatch in Action

Typical Fast-Path Hit

$ omarchy theme set dark

Behind the scenes:

Probe: omarchy-theme-set-dark → not found
Probe: omarchy-theme-set      → found at bin/omarchy-theme-set
Execute: bin/omarchy-theme-set with argument "dark"

Multi-Level Subcommand

$ omarchy hw asus rog status

Resolution sequence:

Probe: omarchy-hw-asus-rog-status → not found
Probe: omarchy-hw-asus-rog        → found at bin/omarchy-hw-asus-rog
Execute: bin/omarchy-hw-asus-rog with leftover argument "status"

Metadata Fallback Scenario

$ omarchy share

When fast-path fails:

Probe: omarchy-share → not found (no such binary)
Fallback: Load metadata from all bin/omarchy-* files
Match: bin/omarchy-menu-share declares canonical route "share"
Execute: bin/omarchy-menu-share

Why the Fast-Path Dispatch Matters

Design Choice	Performance Impact	Maintainability Benefit
Hyphenated naming convention	Direct filesystem mapping without parsing	Self-documenting command structure
First-match termination	O(n) stat calls where n = argument count	Predictable resolution order
Lazy metadata loading	Metadata parsing skipped for ~95% of invocations	Metadata format can evolve without breaking fast-path
Leftover argument passing	Zero argument reconstruction overhead	Commands control their own subcommand parsing

The metadata format is documented in agents/skills/command-metadata.md, using structured comment headers that the fallback parser extracts only when necessary.

Key Implementation Files

• bin/omarchy — Core router implementing fast-path probe and fallback logic
• docs/cli-router.md — Algorithm specification and behavior guarantees
• agents/skills/command-metadata.md — Comment-based metadata format specification
• bin/omarchy-* — Individual command binaries discovered by the fast-path

Summary

• Fast-path dispatch avoids all metadata parsing through hyphenated filename probing
• Progressive prefix matching stops at the first existing binary, passing remaining arguments through
• Filesystem-only hot path uses stat calls exclusively, maintaining low latency at scale
• Metadata fallback preserves flexibility for aliases and renamed commands without penalizing typical usage
• Consistent naming convention (omarchy-<group>-<name>) enables predictable binary discovery

Frequently Asked Questions

What happens if two binaries could match the same command prefix?

The fast-path stops at the first existing binary with the longest matching prefix. In omarchy theme set dark, if both omarchy-theme-set-dark and omarchy-theme-set existed, the more specific binary wins. This deterministic behavior is documented in docs/cli-router.md.

How does the router handle unknown commands?

When neither fast-path nor metadata resolution succeeds, the router exits with status 127 and prints a "did you mean" suggestion based on available routes. No partial execution occurs.

Can I disable the fast-path for debugging?

The router does not expose a disable flag, but you can observe fallback behavior by invoking a command whose hyphenated binary does not exist. The metadata parsing trigger is transparently logged to stderr when OMARCHY_DEBUG=1 is set (per bin/omarchy implementation).

Why use hyphens instead of subdirectories for command organization?

Flat bin/ structure with hyphenated names maintains O(1) directory entries and enables the fast-path stat strategy. Nested directories would require recursive traversal, eliminating the performance advantage of the current design.

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