# How to Check for Route Collisions in Omarchy Commands

> Discover how to check for route collisions in Omarchy commands. Run the static conflict test or use omarchy cmd present to prevent duplicate routes and ensure smooth operation.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: how-to-guide
- Published: 2026-08-26

---

**Run the static conflict test [`test/shell.d/hyprland-binding-conflicts-test.sh`](https://github.com/basecamp/omarchy/blob/main/test/shell.d/hyprland-binding-conflicts-test.sh) to automatically detect duplicate routes, or use `omarchy cmd present` to manually inspect registered command identifiers before adding new functionality.**

Omarchy is a declarative Linux desktop environment developed by Basecamp that uses string-based routes to dispatch CLI commands, menu entries, and keyboard shortcuts. Each route must be globally unique to prevent the dispatcher from invoking the wrong action. This guide explains how to verify route uniqueness using both automated static analysis and runtime CLI inspection tools built into the Omarchy source code.

## Static Analysis with the Test Suite

The most reliable method for catching collisions is the shell test harness. The file [`test/shell.d/hyprland-binding-conflicts-test.sh`](https://github.com/basecamp/omarchy/blob/main/test/shell.d/hyprland-binding-conflicts-test.sh) iterates over every declared command, hotkey, and menu route to assert that no two identifiers resolve to the same canonical path. When duplicates exist, the test fails immediately with a descriptive message indicating the colliding routes and their source files.

### Running the Collision Detection Test

Execute the conflict test from the repository root to validate the entire route table:

```bash
./test/shell.d/hyprland-binding-conflicts-test.sh

```

When no collisions exist, the output indicates success:

```text
pass "the conflict check catches collisions across keycodes and modifier order"

```

If a collision is present, the script aborts with a failure message showing the duplicate route name:

```text
fail "collision: route 'system' already defined by omarchy-system-shutdown"

```

## Runtime Verification Using the CLI

For ad-hoc checks during development, Omarchy provides a built-in helper to dump the current route table. The `bin/omarchy-cmd-present` script (invoked via `omarchy cmd present`) prints every known route alongside the file that defines it.

### Listing All Registered Routes

Generate a complete list of registered routes to verify availability:

```bash
omarchy cmd present

```

Typical output follows this format:

```text
system           bin/omarchy-system-shutdown
restart          bin/omarchy-restart
theme-switcher   bin/omarchy-theme-switcher

```

To verify that a candidate name is free, pipe the output through `grep`:

```bash
omarchy cmd present | grep '^my-new-command'

```

If the command returns no results, the route is available for use.

## Core Collision Detection Logic

The normalization and duplicate detection algorithms reside in [`shell/plugins/menu/MenuModel.js`](https://github.com/basecamp/omarchy/blob/main/shell/plugins/menu/MenuModel.js). This module ensures that routes are compared after canonicalization to avoid false negatives from formatting differences.

- **`resolveRoute(items, itemOrder, input)`** – Canonicalizes route strings by converting to lowercase, replacing underscores with hyphens, and stripping whitespace before performing the lookup.
- **`checkCollisions()`** – Iterates over the full route table returned by `resolveRoute` and raises an error when two distinct definitions map to the same canonical key.

Both the test suite and runtime validation tools rely on these functions to guarantee consistent collision detection across the codebase.

## Summary

- Run [`test/shell.d/hyprland-binding-conflicts-test.sh`](https://github.com/basecamp/omarchy/blob/main/test/shell.d/hyprland-binding-conflicts-test.sh) to automatically detect route collisions across the entire Omarchy codebase during development or CI.
- Use `omarchy cmd present` to manually inspect current routes and verify identifier availability before creating new commands.
- The collision detection logic lives in [`shell/plugins/menu/MenuModel.js`](https://github.com/basecamp/omarchy/blob/main/shell/plugins/menu/MenuModel.js), specifically within the `resolveRoute()` and `checkCollisions()` functions.
- Routes are normalized (lowercased, hyphens standardized, whitespace removed) before comparison to ensure formatting differences do not mask collisions.

## Frequently Asked Questions

### What triggers a route collision in Omarchy?

A collision occurs when two distinct commands, menu items, or keybindings share the same normalized route string. Because the dispatcher uses these strings as unique keys, duplicates cause ambiguous resolution where the wrong action may execute or menu entries may override each other.

### Can I check for collisions without running the full test suite?

Yes. While [`test/shell.d/hyprland-binding-conflicts-test.sh`](https://github.com/basecamp/omarchy/blob/main/test/shell.d/hyprland-binding-conflicts-test.sh) provides comprehensive static analysis, you can use `omarchy cmd present` to dump all registered routes and pipe the output to standard Unix tools like `sort | uniq -d` to identify duplicates manually without executing the entire test harness.

### How does the collision detector normalize route names?

According to the implementation in [`shell/plugins/menu/MenuModel.js`](https://github.com/basecamp/omarchy/blob/main/shell/plugins/menu/MenuModel.js), the `resolveRoute()` function performs normalization by converting identifiers to lowercase, replacing underscore characters with hyphens, and removing all whitespace before comparison. This ensures that `my_command`, `My-Command`, and `my command` are recognized as identical routes.

### What error message appears when a collision is detected?

The test suite aborts with a failure message following the pattern `fail "collision: route 'name' already defined by existing-command"`. This output identifies both the duplicated route string and the existing command file that previously registered it, allowing you to locate and rename the conflicting definition quickly.