# What Is the Fast Path in the Omarchy CLI Router? > Discover the Omarchy CLI router's fast path for constant-time command lookups. Learn how it efficiently matches executables before falling back to flexible parsing. - Repository: [37signals/omarchy](https://github.com/basecamp/omarchy) - Tags: deep-dive - Published: 2026-08-22 --- **The fast path in the Omarchy CLI router is a constant-time lookup mechanism that joins command arguments with hyphens to check for an exact executable match in the `bin/` directory before falling back to slower, flexible parsing.** The Omarchy CLI employs a two-stage routing architecture to dispatch commands efficiently. Understanding how the **fast path** works is essential for developers extending the `basecamp/omarchy` codebase, as it determines how command names are resolved and executed. ## Understanding the Fast Path Mechanism The router optimizes command resolution by attempting a direct executable lookup before invoking the full-featured parser. This approach eliminates parsing overhead for the most frequently used commands. ### Hyphen-Joined Command Resolution When you run a command like `omarchy theme set`, the router constructs a candidate filename by joining the argument prefixes with hyphens. This transforms the input into `omarchy-theme-set`. According to [`docs/cli-router.md`](https://github.com/basecamp/omarchy/blob/main/docs/cli-router.md) (lines 53-97), the router then checks whether an executable script matching this exact name exists in the `bin/` directory. If the file exists and is executable, the router immediately executes it via `exec`. This bypasses the slower argument parsing, sub-command resolution, and help system loading entirely. ### Constant-Time Executable Lookup The fast path provides **O(1) lookup performance** for commands following the `omarchy--` naming convention. Common commands like `omarchy-theme-set` and `omarchy-toggle` resolve instantly because the router performs a simple filesystem check rather than iterating through complex routing tables. When the router cannot find an exact match in `$OMARCHY_PATH/bin/`, it automatically degrades to the slow path. ### Automatic Fallback to Slow Path If the hyphen-joined command name does not correspond to an executable file, the router falls back to the flexible parsing stage. This slow path handles complex scenarios such as group help loading, partial command matching, and dynamic sub-command discovery. ## Source Code Implementation The fast path logic resides primarily in the entry script `bin/omarchy` and is documented in the CLI router specification. ### Direct Dispatch Logic Under the hood, the entry script implements the fast path with a conditional executable check: ```bash # Example: user runs `omarchy theme set dark` # Fast-path construction: cmd_name="omarchy-theme-set" # Router checks: if [[ -x "$OMARCHY_PATH/bin/$cmd_name" ]]; then exec "$OMARCHY_PATH/bin/$cmd_name" "$@" fi # → the script `bin/omarchy-theme-set` is executed immediately. ``` This pattern ensures that standard commands launch without interpreter overhead. ### Fallback Invocation When the fast path misses, the router delegates to the comprehensive parser: ```bash # Example: `omarchy share` does not have a binary named `omarchy-share` # Fast-path fails, so the router falls back: omarchy-cli-router --fallback "$@" # The fallback routine parses sub-commands, loads group help, etc. ``` ### Key Files in the Routing System - **`bin/omarchy`** – The main entry script that implements the fast-path check by constructing the hyphen-joined command name and verifying its existence in the `bin/` directory. - **[`docs/cli-router.md`](https://github.com/basecamp/omarchy/blob/main/docs/cli-router.md)** – Contains the narrative description of the routing algorithm, including the fast-path definition (lines 53-97). - **`bin/omarchy-theme-set`** and **`bin/omarchy-toggle`** – Examples of individual command executables that the fast path resolves to directly. ## Benefits of the Fast Path Architecture The two-stage design provides distinct advantages for both users and developers extending the CLI. ### Execution Speed Most frequent commands resolve in constant time. By avoiding the overhead of the generic parser, the fast path eliminates milliseconds of startup latency for everyday operations like theme switching or configuration toggles. ### Predictable Command Routing Commands adhering to the `omarchy--` naming convention are guaranteed to use the fast path. This gives developers a clear contract: name your executable correctly, place it in `bin/`, and it will execute immediately without routing overhead. ### Robustness Through Degradation If a command does not conform to the strict naming pattern, the router gracefully falls back to the slower, more permissive parsing logic. This ensures that edge cases, help requests, and dynamic commands still function correctly even when they cannot benefit from the fast path optimization. ## Summary - The fast path joins CLI arguments with hyphens (e.g., `omarchy theme set` becomes `omarchy-theme-set`) to locate executables. - It performs a constant-time filesystem check in the `bin/` directory before invoking slower parsing logic. - Commands matching the `omarchy--` pattern in `basecamp/omarchy` execute immediately via direct `exec` calls. - When no executable match exists, the router transparently falls back to `omarchy-cli-router --fallback` for flexible command resolution. ## Frequently Asked Questions ### What happens when a command doesn't match the fast path? The router delegates execution to the slow path by invoking `omarchy-cli-router --fallback "$@"`. This comprehensive parser handles group help loading, sub-command resolution, and partial matching logic that does not require dedicated executables. ### How do I ensure my custom command uses the fast path? Name your executable using the hyphen-joined convention (`omarchy-your-command`) and place it in the repository's `bin/` directory with executable permissions. The entry script at `bin/omarchy` will discover it automatically during the constant-time lookup phase. ### Where is the fast path logic documented? The routing algorithm is documented in [`docs/cli-router.md`](https://github.com/basecamp/omarchy/blob/main/docs/cli-router.md) (specifically lines 53-97), which explains how argument prefixes are joined with hyphens and how the router distinguishes between fast-path execution and fallback processing. ### Is the fast path faster than traditional CLI parsing? Yes. The fast path eliminates the overhead of argument parsing and routing table iteration by performing a direct filesystem executable check. This provides O(1) resolution for compliant commands versus the O(n) complexity typically associated with dynamic CLI routers.