How Slow-Path Dispatch Works in the Omarchy CLI: A Complete Technical Breakdown

The Omarchy CLI uses a two-stage dispatch system where the slow-path fallback dynamically discovers commands by scanning script metadata when fast-path lookup fails.

Omarchy's command-line interface implements a two-stage dispatch mechanism that balances speed for common operations with flexibility for extensions. Understanding how slow-path dispatch works in the Omarchy CLI reveals the architectural decisions that let users add commands without modifying core files. This article examines the implementation details in bin/omarchy and the surrounding script ecosystem.

Fast-Path vs. Slow-Path: The Dispatch Architecture

The Omarchy CLI evaluates every invocation through two distinct stages:

1. Fast-path – Immediate lookup in the static GROUP_DESCRIPTIONS table
2. Slow-path – Dynamic discovery by parsing script metadata across bin/

Only when the fast-path fails does the dispatcher engage slow-path dispatch. This design keeps routine commands snappy while preserving extensibility.

The Fast-Path Foundation

In bin/omarchy, the GROUP_DESCRIPTIONS table provides O(1) command resolution. When you run omarchy toggle touchpad, the dispatcher checks this pre-computed mapping:

# Fast-path execution — no file scanning required

$ omarchy toggle touchpad

# Sources bin/omarchy-toggle-touchpad immediately

Commands found here execute without additional filesystem operations.

How Slow-Path Dispatch Engages

The slow-path dispatch activates when any of these conditions occur:

• The command is missing from GROUP_DESCRIPTIONS
• The command is marked hidden=true in the static table
• The script name uses a non-standard naming convention
• The command belongs to an optional group added at runtime

Step-by-Step Slow-Path Execution

The slow-path implementation follows this sequence:

1. Directory scan — The dispatcher iterates through all bin/omarchy-* files

2. Metadata extraction — It invokes omarchy-cmd-present helpers to parse script headers

3. Hidden flag detection — The parser checks for # omarchy:hidden directives in comment blocks

4. Description parsing — Command descriptions are extracted from header comments

5. Fuzzy matching — The dispatcher searches for loose name matches against the user input

6. Execution or error — On match, the script is sourced; otherwise, the "unknown command" help displays

This process is inherently slower due to multiple file reads and parsing operations, but it only runs when necessary.

Practical Code Examples

Discovering Hidden Commands

Hidden commands—those intentionally omitted from GROUP_DESCRIPTIONS—require slow-path dispatch:

# Slow-path: hidden command discovery

$ omarchy hidden secret-feature

# CLI scans all bin/* scripts, parses headers, finds match, executes

Adding Commands Without Core Modifications

The slow-path enables zero-downtime extension:

# Create a new command script with metadata header

$ echo '# omarchy:hidden=false' > bin/omarchy-mygroup-newcmd

$ chmod +x bin/omarchy-mygroup-newcmd

# Immediate availability via slow-path — no GROUP_DESCRIPTIONS edit needed

$ omarchy mygroup newcmd

The new command works instantly because the slow-path scanner discovers it dynamically.

Key Implementation Files

Understanding slow-path dispatch requires familiarity with these source files:

File	Function in Dispatch
bin/omarchy	Contains GROUP_DESCRIPTIONS table and fast-path logic; implements fallback to slow-path
bin/omarchy-*	Individual command scripts with parseable metadata headers
AGENTS.md	Documents the command-group architecture governing dispatch behavior
docs/testing.md	Houses test coverage for both dispatch paths

The dispatcher in bin/omarchy orchestrates the transition between paths. When fast-path lookup returns no result, control flows to the slow-path routine that leverages omarchy-cmd-present utilities for metadata extraction.

Performance Characteristics

Aspect	Fast-Path	Slow-Path
Time complexity	O(1)	O(n) — scales with script count
Filesystem operations	None	Multiple reads per script
Use case	Standard commands	Hidden, optional, or new commands
Flexibility	Fixed at startup	Runtime extensible

The Omarchy CLI optimizes for the common case: most daily operations hit the fast-path and execute instantly. The slow-path trade-off—accepting latency for flexibility—only affects edge cases.

Design Rationale: Why Two Paths?

The dual-path architecture serves competing requirements:

• Speed — Core commands must feel instantaneous
• Extensibility — Users need to add functionality without forking
• Hidden features — Some commands exist but shouldn't clutter help output
• Optional components — Plugin-like groups may or may not be present

Slow-path dispatch resolves this tension. It keeps the critical path minimal while providing an escape hatch for everything else.

Summary

• Slow-path dispatch activates when fast-path lookup fails in bin/omarchy
• It dynamically discovers commands by scanning and parsing bin/omarchy-* script metadata
• The omarchy-cmd-present helpers extract hidden flags and descriptions from header comments
• Users can add commands without editing GROUP_DESCRIPTIONS—the slow-path finds them automatically
• Performance cost is isolated to rare invocations; common commands remain O(1)

Frequently Asked Questions

What triggers slow-path dispatch in Omarchy?

Slow-path dispatch triggers when a command is absent from the GROUP_DESCRIPTIONS table, marked as hidden, or uses a non-standard naming convention. Any fast-path lookup failure automatically invokes the dynamic discovery mechanism.

How does omarchy-cmd-present work?

The omarchy-cmd-present utilities parse script header comments to extract metadata directives like # omarchy:hidden. These helpers enable the slow-path to build a runtime catalogue of available commands without requiring a central registry.

Can I disable slow-path dispatch for performance?

No—the slow-path is a hardcoded fallback in bin/omarchy. However, you can ensure your commands use the fast-path by adding them to GROUP_DESCRIPTIONS with hidden=false. This requires editing the core dispatcher but eliminates scanning overhead.

What's the performance difference between paths?

Fast-path executes in constant time with zero filesystem operations. Slow-path scales linearly with the number of scripts in bin/, performing multiple reads and parses. In practice, this difference is only perceptible when invoking rarely-used or newly-added commands.

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