How the Fast Path Dispatch Optimizes Omarchy Command Resolution

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, 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 <group> <action>, 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-<group>-<action> (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:

# Fast path success: binary exists, immediate execution

$ omarchy font list

# Internal logic:

#   cmd_name="omarchy-font-list"

#   command -v "$cmd_name" && exec "$cmd_name" "$@"

# Multi-word actions use the same hyphenation pattern

$ omarchy dev status

# Resolves to: omarchy-dev-status

# Bypasses metadata tables entirely

# 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-<group>-<action> 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-<group>-<action>) 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 documents the routing algorithm and the separation between fast and slow paths.

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