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

> Learn how to check for route collisions in Omarchy commands with `omarchy commands --check`. Detect binary route issues, missing metadata, and invalid booleans. A complete guide.

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

---

**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:

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

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

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

```bash
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`](https://github.com/omacom/omarchy/blob/main/docs/cli-router.md) — Routing algorithm and collision definition (lines 32–34)
- `bin/omarchy` — `GROUP_DESCRIPTIONS` table and dispatch logic
- [`docs/menu.md`](https://github.com/omacom/omarchy/blob/main/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`.