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

> Discover how Omarchy CLI's slow-path dispatch dynamically finds commands by scanning script metadata after fast-path lookup fails. Learn the technical details.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: deep-dive
- Published: 2026-09-02

---

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

```bash

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

```bash

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

```bash

# 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`](https://github.com/omacom/omarchy/blob/main/AGENTS.md) | Documents the command-group architecture governing dispatch behavior |
| [`docs/testing.md`](https://github.com/omacom/omarchy/blob/main/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.