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

> Discover how Omarchy CLI's fast-path dispatch uses two-stage routing to speed up command invocations, even with hundreds of commands. Learn about filesystem stat calls and metadata parsing.

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

---

**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`](https://github.com/omacom/omarchy/blob/main/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

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

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

```bash
$ 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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/docs/cli-router.md)** — Algorithm specification and behavior guarantees
- **[`agents/skills/command-metadata.md`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/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.