How Omarchy's Fast Path Bypasses Metadata Parsing for Instant CLI Dispatch

Omarchy's fast path skips metadata parsing by probing the filesystem with simple stat calls on hyphen-joined command prefixes, executing matching binaries immediately without reading file contents.

The Omarchy command-line framework achieves sub-millisecond command routing through a two-stage resolution pipeline. The first stage—called the fast path—resolves most user requests using only filename probes, deliberately avoiding the comment-header metadata that powers the framework's advanced routing features.

This article breaks down exactly how Omarchy implements this optimization, referencing the source implementation in bin/omarchy and the design documentation in docs/cli-router.md.

How the Fast Path Constructs Executable Candidates

When a user invokes omarchy theme set dark, the router doesn't immediately know which binary handles this request. Instead, it generates candidate filenames by progressively joining arguments with hyphens.

The algorithm produces these candidates in order:

1. omarchy-theme-set-dark
2. omarchy-theme-set
3. omarchy-theme

Source: [docs/cli-router.md lines 53-55](https://github.com/omacom/omarchy/blob/quattro/docs/cli-router.md#L53-L55)

For each candidate, the router performs a minimal filesystem probe: a stat system call that checks existence and executability. No file contents are examined. The moment a matching binary is found, the router executes it directly.

# The router's internal resolution for this command:

$ omarchy theme set dark

# 1. stat("omarchy-theme-set-dark") → not found

# 2. stat("omarchy-theme-set")      → found, executable

# 3. exec("omarchy-theme-set") with remaining args ["dark"]

This construction strategy guarantees that the most specific command wins while requiring zero parsing overhead.

Why Stat-Only Probes Avoid Metadata Entirely

Metadata in Omarchy lives in comment headers within each command binary. These headers declare canonical routes, aliases, dependencies, and grouped help categories. Parsing them requires:

• Opening the file
• Reading the header section
• Extracting structured fields from comment blocks

The fast path deliberately never performs these operations. According to the design documentation, the router asks only: "Does this file exist and is it executable?"

Source: [docs/cli-router.md lines 56-58](https://github.com/omacom/omarchy/blob/quattro/docs/cli-router.md#L56-L58)

By restricting itself to stat semantics, the fast path maintains constant-time complexity relative to the number of installed commands. Whether Omarchy ships with 50 or 500 commands, a fast-path resolution requires at most one stat per argument—typically 2-4 system calls total.

Lazy Metadata Loading Falls Back Only When Needed

The fast path's success does not trigger any metadata operations. The resolved binary executes without the router ever reading its comment header.

Metadata becomes relevant in two scenarios only:

• Help display: When the user requests --help for a complex command with grouped subcommands, the router loads metadata to build the help structure.

• Fast-path failure: When no candidate binary matches, the router abandons the fast path and enters metadata-driven resolution.

Source: [docs/cli-router.md lines 59-65](https://github.com/omacom/omarchy/blob/quattro/docs/cli-router.md#L59-L65)

# Fast-path succeeds — no metadata parsed

$ omarchy theme set dark

# → Direct exec of omarchy-theme-set

# Fast-path fails — metadata consulted

$ omarchy share

# → No file "omarchy-share" exists

# → Router loads all command headers via metadata parsing

# → Discovers command with canonical route "share"

# → Executes mapped binary

This lazy approach ensures that metadata parsing—an O(n) operation over all installed commands—runs only for the minority of invocations that actually need it.

The Metadata-Driven Fallback Path

When fast-path lookup exhausts all candidates without finding an executable, Omarchy switches to comprehensive resolution:

1. Load all headers: Every binary's comment header is parsed into a route table.
2. Apply longest-prefix matching: The framework supports commands whose binaries don't match their invocation names—useful for renamed commands and aliases.
3. Resolve and execute: The matching command's actual binary location is determined from metadata and executed.

Source: [docs/cli-router.md lines 62-65](https://github.com/omacom/omarchy/blob/quattro/docs/cli-router.md#L62-L65)

This fallback guarantees that advanced routing features remain available without penalizing common-case performance.

Key Implementation Files

File	Purpose
docs/cli-router.md	Documents the fast-path algorithm and two-stage resolution (lines 53-65)
bin/omarchy	Router entry point containing GROUP_DESCRIPTIONS and fast-path stat logic
agents/skills/command-metadata.md	Comment-header format specification—only parsed during fallback
bin/omarchy-*	Individual binaries executed directly by fast-path matches

Summary

• Fast-path bypasses metadata parsing by constructing hyphen-joined candidate names and probing with stat only.
• Zero file content reads occur during successful fast-path resolution.
• Metadata loads lazily—only when help is requested or no binary matches.
• Fallback resolution provides metadata-driven routing for aliases and renamed commands without impacting hot-path latency.

Frequently Asked Questions

What happens if two commands have similar names?

The fast path tries the most specific candidate first. For omarchy theme set, it probes omarchy-theme-set before omarchy-theme. This longest-prefix behavior ensures correct dispatch without ambiguity resolution overhead.

Does the fast path support command aliases?

No—aliases require metadata parsing to discover the mapping from alias name to actual binary. Aliased commands trigger the fallback path, which loads all headers to resolve the canonical route.

How does this compare to traditional CLI frameworks?

Most frameworks parse subcommand structures from metadata or configuration files on every invocation. Omarchy's stat-first approach inverts this: assume the common case needs no metadata, and pay the parsing cost only when flexibility demands it.

Can the fast path be disabled?

No explicit switch exists in the documented implementation. The architecture inherently prefers fast-path success; metadata loading is a reactive fallback rather than a configurable mode.

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