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

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:

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

# 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

# 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 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 with metadata specifications in 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.

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