# How Omarchy Detects Route Collisions: Static Analysis of CLI Command Routing

> Omarchy statically detects route collisions during router initialization by mapping route strings to binaries, logging conflicts for duplicate registrations.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: internals
- Published: 2026-08-31

---

**Omarchy detects route collisions statically during router initialization by maintaining a mapping from route strings to binaries, logging conflicts when duplicate routes attempt to register.**

Omarchy's command-line interface uses a dynamic routing system built by scanning `bin/omarchy-*` executables. Understanding how Omarchy detects route collisions helps developers avoid naming conflicts when adding custom commands. The collision detection logic runs entirely at router build time, ensuring predictable behavior before any user command executes.

## How Omarchy Builds Its Route Table

The Omarchy router constructs its command table by examining every executable matching the pattern `bin/omarchy-*`. In `bin/omarchy`, this scan generates **two distinct routes** for each binary:

- **Canonical route** — derived from metadata comments (`# omarchy:group=…` and `# omarchy:name=…` found in the file)

- **Filename route** — created by replacing hyphens with spaces in the filename (e.g., `omarchy-theme-set` becomes `theme set`)

Both routes point to the same binary and compete for registration in the global route map.

## The Collision Detection Mechanism

Collisions occur when two different binaries claim identical route strings. The router implements this check using a bash associative array `ROUTE_TO_KEY` that maps routes to their originating binaries.

At line 158 in `bin/omarchy`, the detection logic appends violations to a dedicated array:

```bash
ROUTE_COLLISIONS+=("$route -> ${ROUTE_TO_KEY[$route]} conflicts with $key")

```

Key characteristics of Omarchy's collision detection:

**First registration wins.** The binary that registers a route first retains ownership. Subsequent binaries attempting the same route are recorded as collisions but remain executable.

**Static analysis only.** No runtime collision detection occurs—all conflicts are identified during router initialization.

**Hidden commands participate.** Binaries marked with `# omarchy:hidden=true` still undergo collision checking; the flag only affects command listings, not routing validation.

## Viewing Detected Collisions

Omarchy provides built-in visibility into route conflicts through the `--check` flag.

### Run the Collision Check

```bash

# Check all commands for route collisions

omarchy commands --check

# Or use the shorthand

omarchy --check

```

### Sample Output

```

Route collision: theme set -> bin/omarchy-theme-set conflicts with bin/omarchy-theme-set-alt
Route collision: power off -> bin/omarchy-hw-power-off conflicts with bin/omarchy-power-off

```

### Filter Collisions in Scripts

```bash

# Extract only collision lines for programmatic processing

omarchy --check | grep 'Route collision'

```

## Route Metadata and Collision Sources

Command metadata defined in [`agents/skills/command-metadata.md`](https://github.com/omacom/omarchy/blob/main/agents/skills/command-metadata.md) directly influences route generation. The `group` and `name` keys combine to form canonical routes, while filenames provide the literal route alternative.

| Metadata Key | Effect on Routing | Collision Risk |
|-------------|-------------------|----------------|
| `group` | Prefixes canonical route | Duplicate with other groups |
| `name` | Suffixes canonical route | Duplicate within same group |
| `hidden` | Excludes from `commands` listing | **Still collides if routes match** |

A binary named `omarchy-theme-set` with metadata `group=theme, name=set` creates:

- Canonical route: `theme set`
- Filename route: `theme set`

Both routes identical—no collision with itself, but any other binary producing `theme set` triggers a conflict.

## Preventing Collisions

Follow these practices to avoid route collisions in Omarchy:

- **Verify uniqueness before adding** — run `omarchy --check` after installing new commands
- **Coordinate metadata and filename** — ensure `group`+`name` combinations don't match hyphen-replaced filenames of other binaries
- **Namespace custom commands** — use distinctive group names (e.g., `acme-deploy` rather than `deploy`)

## Summary

- Omarchy detects route collisions **statically** during router initialization by scanning `bin/omarchy-*` binaries
- Each binary registers **two routes**: canonical (from metadata) and filename-based (hyphens-to-spaces)
- The router stores conflicts in `ROUTE_COLLISIONS` (line 158 of `bin/omarchy`) with **first-registration-wins** semantics
- Use `omarchy commands --check` or `omarchy --check` to view all detected collisions
- Hidden commands still participate in collision detection despite being omitted from listings
- Core documentation resides in [`docs/cli-router.md`](https://github.com/omacom/omarchy/blob/main/docs/cli-router.md) with metadata specifications in [`agents/skills/command-metadata.md`](https://github.com/omacom/omarchy/blob/main/agents/skills/command-metadata.md)

## Frequently Asked Questions

### What causes a route collision in Omarchy?

A route collision occurs when two different binaries register identical command routes. This happens when filename routes (hyphens converted to spaces) match canonical routes (built from `group` and `name` metadata) from separate binaries. The router logs these conflicts in `ROUTE_COLLISIONS` during initialization.

### Does Omarchy prevent conflicting commands from running?

No. Omarchy does not block execution of binaries involved in collisions. The first binary to register a route wins routing priority, but all binaries remain executable directly. The collision warning alerts administrators to ambiguous command paths that may confuse users.

### How do hidden commands affect collision detection?

Hidden commands undergo full collision detection despite being excluded from `omarchy commands` output. The `# omarchy:hidden=true` metadata flag only suppresses listing visibility—it does not exempt the binary from route registration or conflict checking.

### Where is the collision detection code located?

The collision detection logic is implemented in `bin/omarchy` at approximately line 158, where the router checks `ROUTE_TO_KEY[$route]` before registration. The associative array tracks route-to-binary mappings, and conflicts append to the `ROUTE_COLLISIONS` array for later reporting.