How Omarchy Detects Route Collisions with `omarchy commands --check`

omarchy commands --check detects route collisions by building a map of all command routes at runtime and flagging any duplicate entries where two different binaries claim the same invocation string.

Route collision detection in Omarchy's CLI ensures that every command has a unique, unambiguous entry point. When you run omarchy commands --check, the system scans all binaries in bin/, registers their routes and aliases, and reports any conflicts that would prevent deterministic command dispatch.

The Route Registration System

Commands in Omarchy declare their invocable routes through metadata comments in their source files. The core CLI driver in bin/omarchy processes these declarations using the register_route function.

How Routes Are Tracked

The ROUTE_TO_KEY associative array (line 24 in bin/omarchy) serves as the central registry. Each entry maps a route (what the user types) to a command key (the internal binary identifier). This mapping happens during the initialization phase when omarchy loads available commands.

register_route() {
    local route="$1"
    local key="$2"
    …
    if [[ -n ${ROUTE_TO_KEY[$route]} && ${ROUTE_TO_KEY[$route]} != "$key" ]]; then
        ROUTE_COLLISIONS+=("$route -> ${ROUTE_TO_KEY[$route]} conflicts with $key")
        return
    fi
    ROUTE_TO_KEY["$route"]="$key"
    …
}

The collision check on lines 58‑60 enforces uniqueness: if a route already exists and points to a different key, the conflict is recorded rather than overwritten.

Collision Detection Logic

Omarchy's detection mechanism is intentionally strict and lightweight. It operates on exact string matches of route names, ignoring arguments, subcommands, or partial overlaps.

What Triggers a Collision

A collision occurs in exactly one scenario: two distinct binaries declare the same route or alias. Common causes include:

• Copying a script and forgetting to update its # omarchy:route= comment

• Adding an alias that matches another command's primary route

• Merging branches where both introduce commands with overlapping names

The ROUTE_COLLISIONS array (line 9) accumulates all conflicts for batch reporting.

The Check Command Implementation

When you execute omarchy commands --check, the show_commands_check function evaluates system health:

show_commands_check() {
    …
    for collision in "${ROUTE_COLLISIONS[@]}"; do
        echo "Route collision: $collision" >&2
        failures=$((failures + 1))
    done
    …
}

Each collision generates a descriptive message sent to stderr, and the final exit status reflects the total failure count.

Example Output and Resolution

Successful Check

$ omarchy commands --check
Command metadata check passed (215 commands)

Detected Collision

Introducing a conflicting alias produces immediate, actionable output:

$ omarchy commands --check
Route collision: update -> omarchy-update conflicts with omarchy-update-aur
Command metadata check failed (1 issues)

The message format clearly identifies:

• The conflicting route: update
• The existing claimant: omarchy-update
• The conflicting binary: omarchy-update-aur

Resolution Steps

1. Identify the source: Locate the # omarchy:route= or # omarchy:aliases= metadata in the second binary

2. Modify the declaration: Change the route to a unique value, or remove the conflicting alias

3. Re-run the check: Verify resolution with omarchy commands --check

# After fix

$ omarchy commands --check
Command metadata check passed (215 commands)

Design Rationale

The Omarchy team chose exact-string matching over fuzzy or hierarchical collision detection for predictability. As documented in docs/cli-router.md (lines 32‑125), this approach guarantees that:

• Users never experience ambiguous command dispatch
• Shell completions remain deterministic
• CI pipelines can gate deployments on clean --check results

The lightweight implementation avoids parsing command arguments or subcommand structures, keeping the validation fast and maintainable.

Key Files and Components

• bin/omarchy (lines 8‑67): Core CLI driver implementing register_route, collision detection, and show_commands_check
• docs/cli-router.md (line 121): Formal definition of route collisions as "two routes claiming different binaries"
• bin/ directory: All scanned binaries containing metadata declarations

Summary

• Route registration populates ROUTE_TO_KEY with mappings from invocation strings to binary keys
• Collision detection compares incoming routes against existing entries on lines 58‑60 of bin/omarchy
• Conflict reporting aggregates all issues in ROUTE_COLLISIONS for batch output via show_commands_check
• Exit behavior returns non-zero status when any collisions are found, enabling CI integration

Frequently Asked Questions

What qualifies as a route collision in Omarchy?

A route collision occurs when two different binaries register identical route strings. This includes primary routes (# omarchy:route=) and aliases (# omarchy:aliases=). The system does not detect partial matches or argument-pattern conflicts—only exact string duplicates trigger warnings.

Where is collision detection implemented in the source code?

The core logic resides in bin/omarchy, specifically the register_route function spanning lines 24‑67. The check condition on lines 58‑60 compares incoming routes against the ROUTE_TO_KEY associative array, and show_commands_check handles output formatting.

Can route collisions exist without breaking normal omarchy operation?

No. While the system may arbitrarily pick one command during interactive use, omarchy commands --check is designed to fail-fast and prevent deployment of conflicting configurations. The collision-finding behavior is deterministic: the first-registered route wins, and subsequent duplicates are rejected.

How do I debug an unexpected route collision?

Run omarchy commands --check to identify the conflicting route and binaries. Then search bin/ for the route string in metadata comments—typically # omarchy:route= or # omarchy:aliases= declarations. Modify or remove the duplicate entry and re-run the check to confirm resolution.

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