# How the Fast Path Dispatch Optimizes Omarchy Command Resolution > Learn how the fast path dispatch optimizes Omarchy command resolution by directly executing binaries, bypassing parsing and conflict resolution for faster command execution. - Repository: [Omacom/omarchy](https://github.com/omacom/omarchy) - Tags: internals - Published: 2026-09-11 --- **The fast path dispatch optimizes Omarchy command resolution by concatenating the group and action into a hyphenated binary name, performing a single `$PATH` lookup via `command -v`, and immediately executing the binary if found, thereby bypassing all metadata parsing and conflict resolution logic.** The command-line interface in `omacom/omarchy` resolves user requests through a deliberately optimized two-stage router. The **fast path dispatch** serves as the primary mechanism for command resolution, handling the majority of invocations with minimal latency by avoiding complex metadata tables. This design ensures that common commands like `omarchy font list` execute with virtually zero routing overhead. ## Understanding the Two-Stage Router Architecture The Omarchy CLI router operates in two distinct phases to balance speed with flexibility. The **fast path** handles the most common invocations through simple filesystem lookups, while the **slow path** manages edge cases, hidden commands, and alias resolution. According to the source code in [`docs/cli-router.md`](https://github.com/omacom/omarchy/blob/main/docs/cli-router.md), this architecture ensures that standard commands never pay the performance penalty of parsing the `GROUP_DESCRIPTIONS` table or resolving command conflicts. ## Fast Path Dispatch Mechanics When a user invokes `omarchy `, the router immediately attempts the fast path resolution. ### Argument Concatenation and Binary Naming In `bin/omarchy`, the dispatcher constructs the target binary name by joining the command group and sub-command with hyphens. The router builds the string `omarchy--` (e.g., `omarchy-font-list` for `omarchy font list`). This naming convention creates a deterministic mapping between user input and executable files without requiring metadata lookups. ### $PATH Lookup and Immediate Execution The dispatcher then checks for the existence of this binary using `command -v "$cmd_name"`. If the binary exists in `$PATH`, the router immediately hands off control via `exec "$cmd_name" "$@"`, replacing the current process entirely. Because this implementation performs only a single filesystem check before execution, it incurs virtually no overhead compared to direct binary invocation. ## When the Fast Path Fails: Slow Path Fallback If `command -v` returns a non-zero status, indicating the hyphenated binary does not exist, the router falls back to the slow path. This alternative route examines the `GROUP_DESCRIPTIONS` table, resolves hidden commands, merges aliases, and records any conflicts between command names. The slow path provides the flexibility to handle dynamic or overridden commands at the cost of additional parsing overhead. ## Code Examples: Fast Path in Action The following examples demonstrate how `bin/omarchy` handles different invocation patterns: ```bash # Fast path success: binary exists, immediate execution $ omarchy font list # Internal logic: # cmd_name="omarchy-font-list" # command -v "$cmd_name" && exec "$cmd_name" "$@" ``` ```bash # Multi-word actions use the same hyphenation pattern $ omarchy dev status # Resolves to: omarchy-dev-status # Bypasses metadata tables entirely ``` ```bash # Slow path triggered: binary not found $ omarchy unknown command # Falls back to GROUP_DESCRIPTIONS lookup # Performs alias resolution and conflict checking ``` ## Performance Impact and Hot Path Optimization The fast path serves as the **hot path** for the majority of user interactions. By handling frequent cases—such as `omarchy share`, `omarchy font list`, or `omarchy dev status`—with a single `$PATH` lookup, Omarchy maintains sub-millisecond dispatch latency. The explicit separation between fast and slow paths ensures that edge-case complexity never degrades the performance of standard operations. ## Summary - **Fast path dispatch** concatenates group and action into `omarchy--` and performs a direct `$PATH` lookup. - If the binary exists, the router executes immediately via `exec`, skipping all metadata processing. - Only missing binaries trigger the **slow path**, which parses `GROUP_DESCRIPTIONS` and resolves aliases. - This two-stage design optimizes for the common case, keeping the CLI responsive for standard commands. ## Frequently Asked Questions ### What is the fast path dispatch in Omarchy? The fast path dispatch is Omarchy's primary command resolution mechanism that converts user input into a hyphenated binary name and checks `$PATH` for immediate execution, bypassing metadata tables entirely. ### How does Omarchy handle commands that don't have a dedicated binary? When the hyphenated binary does not exist in `$PATH`, the router falls back to the slow path, which consults the `GROUP_DESCRIPTIONS` table, resolves hidden commands, and processes aliases to locate the appropriate handler. ### Why does the fast path use hyphenated binary names? The hyphenated naming convention (`omarchy--`) creates a deterministic filesystem mapping that allows the router to resolve commands through simple `command -v` lookups rather than parsing complex configuration data. ### Where is the fast path logic implemented in the source code? The fast path logic resides primarily in `bin/omarchy`, which constructs the binary name and performs the lookup, while [`docs/cli-router.md`](https://github.com/omacom/omarchy/blob/main/docs/cli-router.md) documents the routing algorithm and the separation between fast and slow paths.