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

> Learn how omarchy commands --check detects route collisions by mapping command routes at runtime and flagging duplicate entries. Prevent conflicts in your binaries.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: how-to-guide
- Published: 2026-09-06

---

**`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.

```bash
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:

```bash
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

```bash
$ 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`

```bash

# 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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/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.