# Omarchy Fast Path Resolution Strategy: How Commands Are Resolved Without Metadata > Discover Omarchy's fast path resolution strategy. Learn how commands resolve instantly by probing the filesystem for executables before metadata loading. - Repository: [Omacom/omarchy](https://github.com/omacom/omarchy) - Tags: internals - Published: 2026-09-08 --- **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: ```bash 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`](https://github.com/omacom/omarchy/blob/main/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: ```bash 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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/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--` and are probed directly by the router. - **[`agents/skills/command-metadata.md`](https://github.com/omacom/omarchy/blob/main/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: ```bash # 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 ``` ```bash # 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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/docs/cli-router.md) at lines 53-56, with the actual binary implementations residing in the `bin/` directory following the `omarchy-*` naming convention.