What Is the Fast Path in the Omarchy CLI Router?

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

# 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:

# 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 – 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-<group>-<action> 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-<group>-<action> 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 (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.

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