# What Is the Fast Path for Omarchy CLI Command Resolution?

> Discover the fast path for Omarchy CLI command resolution. Learn how hyphen-joined filenames speed up executable binary checks before metadata loading, avoiding comment block parsing overhead.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: internals
- Published: 2026-08-29

---

**The fast path for Omarchy CLI command resolution is a hyphen-joined filename probe that checks for executable binaries matching command arguments before loading any metadata, avoiding the overhead of parsing comment blocks.**

Omarchy, the Arch-based Linux distribution developed by Basecamp, implements a flat executable namespace for its CLI router located in `bin/omarchy-*`. When you invoke a command like `omarchy theme set foo`, the router prioritizes speed by attempting to resolve the command through direct filesystem checks before falling back to metadata parsing.

## How the Fast Path Works

The fast path operates as a "hot path" optimization that minimizes filesystem and parsing overhead during Omarchy CLI command resolution. According to the router implementation in [`docs/cli-router.md`](https://github.com/basecamp/omarchy/blob/main/docs/cli-router.md) (lines 53-60), the algorithm probes candidate executables by transforming argument prefixes into hyphen-separated filenames.

### Hyphen-Joined Filename Probing

The router concatenates each argument prefix with hyphens and checks for the existence of matching executable files in the `bin/` directory. 

For example, when executing `omarchy theme set foo`:

1. Probes `bin/omarchy-theme-set-foo`
2. Falls back to `bin/omarchy-theme-set`
3. Executes the first match found, passing remaining arguments

This linear probe executes simple `stat` calls on a small number of candidate binaries, making it significantly faster than parsing configuration files.

### Zero Metadata Overhead

When the fast path succeeds, the router dispatches to the executable **immediately** without reading a single metadata header. This design avoids the overhead of parsing potentially hundreds of comment blocks that define command metadata, such as those documented in [`agents/skills/command-metadata.md`](https://github.com/basecamp/omarchy/blob/main/agents/skills/command-metadata.md).

The lazy loading approach ensures that metadata is only parsed for the specific binary when help text or introspection is explicitly requested, not during routine command execution.

### Fallback to Metadata Resolution

If no hyphen-joined filename matches the command arguments, the router triggers the fallback mechanism:

1. Reads metadata headers from all command binaries
2. Builds a complete route table based on `# omarchy:name=` declarations

3. Resolves using the longest-prefix matching rule
4. Executes the matched binary

This two-tier architecture ensures common commands execute with minimal latency while complex routing scenarios remain supported.

## Fast Path vs. Metadata Resolution

Understanding the distinction between these resolution strategies helps optimize your Omarchy CLI usage:

**Fast Path Resolution**
- Performs filesystem `stat` checks on 2-4 candidate filenames
- Zero parsing overhead
- Immediate execution upon match
- Used for 90%+ of standard commands

**Metadata Resolution**
- Parses comment blocks from all binaries in `bin/`
- Builds routing tables dynamically
- Supports aliases and complex argument routing
- Only triggered when fast path fails

## Practical Code Examples

The following examples demonstrate how the fast path resolves commands in the Basecamp Omarchy repository:

```bash

# Fast path example – the binary exists, so no metadata is parsed

$ omarchy theme set dark

# The router probes:

#   1) omarchy-theme-set-dark  (not found)

#   2) omarchy-theme-set      (found) → exec bin/omarchy-theme-set dark

```

```bash

# When no matching filename exists, the router falls back to metadata

$ omarchy share

# No bin/omarchy-share binary → router loads metadata, finds the canonical route

# defined by `# omarchy:name=` in omarchy-menu-share, then execs that binary.

```

```bash

# Using the fast path with extra arguments passed through

$ omarchy update aur --dry-run

# Probes omarchy-update-aur-dry-run → not found,

# then omarchy-update-aur → found → exec bin/omarchy-update-aur --dry-run

```

## Key Implementation Files

The fast path mechanism relies on these critical components in the Omarchy source:

- **[`docs/cli-router.md`](https://github.com/basecamp/omarchy/blob/main/docs/cli-router.md)** – Contains the core algorithm documentation describing the hyphen-joined probe sequence and dispatch rules
- **`bin/omarchy`** – Defines the top-level entry point and the `GROUP_DESCRIPTIONS` table used when listing available commands
- **[`agents/skills/command-metadata.md`](https://github.com/basecamp/omarchy/blob/main/agents/skills/command-metadata.md)** – Documents the comment-based metadata format parsed only when the fast path fails
- **`bin/omarchy-theme-set`** – Example executable demonstrating how fast-path-resolved binaries receive and handle arguments

## Summary

- The **fast path** resolves Omarchy CLI commands by probing hyphen-joined filenames before loading any metadata
- Resolution performs simple filesystem checks on `bin/omarchy-{arg1}-{arg2}...` patterns until finding a match
- Successful fast path execution bypasses metadata parsing entirely, eliminating comment-block overhead
- The mechanism falls back to full metadata resolution only when no direct filename match exists
- This architecture optimizes the common case while maintaining flexibility for complex routing scenarios

## Frequently Asked Questions

### How does Omarchy's fast path differ from traditional CLI routing?

Traditional CLI tools often parse configuration files or command trees before dispatching, while Omarchy's fast path uses direct filesystem probes. The router transforms your command arguments into potential filenames—checking `omarchy-theme-set` before `omarchy-theme`—and executes immediately upon finding a match, avoiding the metadata parsing overhead typical of argparse or commander-style frameworks.

### What happens if I have a command named `omarchy-theme` but type `omarchy theme set`?

The router first probes `bin/omarchy-theme-set` (the complete argument chain), then falls back to `bin/omarchy-theme`. If `bin/omarchy-theme-set` exists as a separate executable, it will receive priority and execute with any remaining arguments. If only `bin/omarchy-theme` exists, that binary receives the `set` argument, allowing for flexible subcommand delegation.

### Why does the fast path improve performance in Omarchy CLI command resolution?

The fast path improves performance by replacing metadata parsing with efficient filesystem `stat` calls. As implemented in [`docs/cli-router.md`](https://github.com/basecamp/omarchy/blob/main/docs/cli-router.md), checking for the existence of 2-4 specific filenames requires microseconds of disk I/O compared to milliseconds of parsing hundreds of comment blocks containing `# omarchy:name=` declarations. This hot-path optimization ensures sub-10ms command startup times for standard operations.

### When does the router skip the fast path entirely?

The router only skips the fast path when no hyphen-joined filename matches the command arguments. This occurs when invoking aliases, menu wrappers like `omarchy-share` (which might route to `omarchy-menu-share` via metadata), or commands that use descriptive names differing from their argument structure. In these cases, the router loads all metadata from `bin/` binaries to build a complete routing table.