How to Check for Route Collisions in Omarchy Commands: A Complete Guide

Run omarchy commands --check to detect route collisions between binaries, missing metadata, and invalid boolean values in the CLI router.

Omarchy's command routing system automatically builds routes from executable scripts named bin/omarchy-*. When two binaries register the same route, route collisions occur—the first registration wins, and subsequent registrations are flagged for developer attention. This guide explains how to detect, inspect, and resolve these collisions.

Understanding Omarchy's Route Registration

Omarchy registers two routes per binary:

• Canonical route: Derived from explicit metadata (# omarchy:name=) or inferred from the filename

• Filename route: Every hyphen in the filename converted to a space

Collisions happen when different binaries claim identical routes. The router continues executing the first registered binary but records the conflict for debugging.

Running the Collision Detector

The built-in lint command surfaces all routing issues:

omarchy commands --check

This validator fails on four categories of problems:

• Route collisions between binaries — multiple executables share one route

• Missing explicit # omarchy:summary= metadata

• Invalid boolean metadata in hidden or requires-sudo fields

• Registered commands with missing or non-executable binaries

Sample Collision Output

$ omarchy commands --check

✗ Route collision: "omarchy share" claimed by:
  - bin/omarchy-menu-share
  - bin/omarchy-share

The output identifies the conflicting route and all binaries involved, enabling targeted fixes.

Inspecting Routes with JSON Output

For detailed debugging, export the full route table:

omarchy commands --all --json | jq '.[] | select(.routes | contains(["omarchy share"]))'

This reveals:

• All registered routes (including hidden commands)
• Which binary resolves for each route
• Original filename routes versus canonical overrides

Verifying Route Resolution

Check any specific route to confirm which binary executes:

omarchy share --help

The help output displays:

• Resolved binary: The actual executable invoked
• Filename route: The space-converted filename that matched

Use this to verify fixes after editing command files.

Resolving Collisions

Adjust these command script attributes to eliminate overlaps:

Approach	Method	Example
Rename the file	Change hyphens	bin/omarchy-menu-share → bin/omarchy-quick-share
Override canonical name	Add metadata	# omarchy:name=omarchy quick share

After modifications, rerun omarchy commands --check to confirm clearance.

Key Source Files

Reference these locations in the omacom/omarchy repository:

• docs/cli-router.md — Routing algorithm and collision definition (lines 32–34)
• bin/omarchy — GROUP_DESCRIPTIONS table and dispatch logic
• docs/menu.md — Menu ID slugification and collision handling (line 115)
• bin/omarchy-* — Command scripts whose filenames generate routes

Summary

• Detection: Use omarchy commands --check to find route collisions and metadata issues

• Inspection: Filter JSON output with jq or query specific routes with --help

• Resolution: Modify filenames or add # omarchy:name= metadata to disambiguate routes

• Verification: Re-run the check command and inspect route resolution to confirm fixes

Frequently Asked Questions

What causes route collisions in Omarchy?

Route collisions occur when two or more bin/omarchy-* executables register identical routes—either through filename conversion or explicit omarchy:name= overrides. The first binary registered wins execution rights.

Does a collision prevent commands from running?

No. The first registered binary continues to execute normally. Collisions are logged purely for developer awareness and cleanup purposes.

How do I change a command's route without renaming the file?

Add an # omarchy:name= metadata line near the top of your command script. This overrides the canonical route while preserving the original filename route.

Can I see hidden commands when debugging collisions?

Yes. Append --all to include hidden commands in the output: omarchy commands --all --json.

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