Omarchy Fast Path Resolution Strategy: How Commands Are Resolved Without Metadata

Omarchy's command router uses a fast-path strategy that resolves commands by probing the filesystem for hyphen-joined binary names before loading any metadata, executing the first matching executable immediately with minimal latency.

The Omarchy CLI employs a lightweight routing mechanism designed to minimize command dispatch overhead. According to the Omarchy source code, this fast path resolution strategy avoids expensive metadata parsing by generating candidate binary names from command arguments and checking for executable files directly on the filesystem. This approach ensures that common command invocations incur only a handful of stat system calls rather than parsing overhead.

How the Fast Path Resolution Strategy Works

When you invoke an Omarchy command, the router immediately enters the fast path before considering any command definitions. The system constructs potential binary names by joining successive argument prefixes with hyphens and checks whether an executable file exists for each candidate.

Hyphen-Joined Binary Probing

The router builds candidate names by progressively combining arguments. For example, when you run:

omarchy theme set foo

The resolution algorithm performs the following probes in order:

1. First, it checks for omarchy-theme-set-foo
2. If not found, it checks for omarchy-theme-set

The first matching binary is executed immediately. As documented in docs/cli-router.md, this hyphen-joined probe sequence allows the router to resolve specific subcommands without parsing header comments or loading command-metadata files.

Minimal Filesystem Overhead

The fast path is deliberately lightweight, issuing only a few stat calls to verify file existence. This design keeps the hot path—plain command dispatch—as fast as possible. Metadata is only read lazily for the resolved command when help text or other introspection features are explicitly requested.

Fallback to Metadata Routing

If the fast path fails to locate a matching binary, Omarchy falls back to metadata-based routing. For instance:

omarchy share

If no omarchy-share binary exists in the bin/ directory, the router abandons the fast path and consults the metadata definitions found in agents/skills/command-metadata.md. This secondary path provides flexibility for commands that do not warrant dedicated binaries while maintaining optimal performance for the common case.

Implementation Details

Source Files and Architecture

The fast path resolution strategy is implemented across several key files in the Omarchy repository:

• docs/cli-router.md (lines 53-56) – Documents the routing algorithm, including the specific logic for hyphen-joined binary probing and the fallback sequence.

• bin/omarchy-* – The individual command binaries that the fast path targets. These executable files follow the naming convention omarchy-<command>-<subcommand> and are probed directly by the router.

• agents/skills/command-metadata.md – Defines the metadata format used only when the fast path does not resolve a command. This file is parsed lazily, ensuring that metadata overhead is avoided until absolutely necessary.

Practical Examples

The following examples demonstrate the fast path in action:

# Fast-path resolution – hyphen-joined probe

omarchy theme set foo      # looks for omarchy-theme-set-foo, then omarchy-theme-set

# If a matching binary exists, it is executed directly

# No metadata parsing occurs for the lookup

# When the fast path fails, Omarchy falls back to metadata

omarchy share              # no `omarchy-share` binary, falls back to metadata routes

Summary

• Omarchy's fast path resolves commands by checking for hyphen-joined binaries before loading any metadata.
• The algorithm probes candidates by joining argument prefixes, checking omarchy-theme-set-foo before falling back to omarchy-theme-set.
• Only a minimal number of stat calls are issued, keeping command dispatch latency low.
• If no binary matches, the system falls back to parsing agents/skills/command-metadata.md.
• This architecture separates high-performance command execution from metadata-driven flexibility.

Frequently Asked Questions

How does Omarchy decide which binary to execute?

Omarchy constructs candidate names by joining your command arguments with hyphens and checks the filesystem in order of specificity. It first looks for the most specific binary (e.g., omarchy-theme-set-foo), then progressively less specific versions (e.g., omarchy-theme-set), executing the first one found.

What happens if no binary matches the command arguments?

If the fast path probe fails to find any matching bin/omarchy-* executable, Omarchy falls back to metadata-based routing. It then parses agents/skills/command-metadata.md to resolve the command through alternative definitions.

Why does Omarchy use a fast path instead of always parsing metadata?

The fast path avoids the overhead of parsing header comments or metadata files for every command invocation. By resolving commands through simple filesystem probes (a few stat calls), Omarchy achieves minimal latency for the hot path while still supporting rich metadata when needed.

Where is the fast path logic documented in the source code?

The algorithm is documented in docs/cli-router.md at lines 53-56, with the actual binary implementations residing in the bin/ directory following the omarchy-* naming convention.

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