How to Check for Route Collisions in Omarchy Commands

Run the static conflict test 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 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:

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

When no collisions exist, the output indicates success:

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:

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:

omarchy cmd present

Typical output follows this format:

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:

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. 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 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, 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 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, 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.

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