Omarchy Longest-Prefix Dispatch Algorithm: How the CLI Router Resolves Commands

Omarchy's command-line router resolves user input by progressively matching the longest registered command prefix, falling back to shorter prefixes until it finds a valid handler.

The omacom/omarchy repository implements a hierarchical CLI where nested sub-commands automatically inherit parent behavior when no more specific match exists. This article explains how the longest-prefix dispatch algorithm works, where it's implemented in the source code, and how to leverage it when building Omarchy command groups.

How the Longest-Prefix Dispatch Algorithm Works

When a user executes omarchy <args…>, the router in bin/omarchy applies a deterministic resolution strategy:

1. Start with the complete argument list — e.g., omarchy foo bar baz

2. Search for an exact match against registered command groups

3. Strip the right-most argument if no match exists, then retry

4. Repeat until a match is found or only the base command remains

5. Pass remaining arguments to the matched command as parameters

This approach ensures that more specific commands take precedence over their parent groups, creating an intuitive namespace for CLI operations.

Source Code Implementation

The dispatch logic resides in bin/omarchy, which performs the prefix-matching and delegates to sub-command handlers. Command definitions and prefix metadata are documented in agents/skills/command-metadata.md, specifying how groups declare their accepted argument patterns.

Documented behavior appears in docs/cli-router.md, which states: "Resolution is longest-prefix: the router tries the full argument list as a command group; if no match, it drops the final argument and retries."

Practical Examples

Exact Match (Full Prefix)

omarchy capture-screenshot

The router locates the exact command capture-screenshot and executes it directly.

Partial Match with Argument Passing

omarchy capture-screenshot screen1 --delay 2

No command registers capture-screenshot screen1 --delay 2 as a valid prefix. The router drops --delay 2 and retries with capture-screenshot screen1. Finding this prefix, it invokes that command with --delay 2 passed as trailing arguments.

Top-Level Fallback

omarchy unknown-command foo bar

When no prefix matches unknown-command or any truncation thereof, control falls to the base omarchy group, which typically renders help text or an error message.

Design Benefits

Characteristic	Result
Specificity priority	Deeply nested commands override parent handlers
Backward compatibility	Adding sub-commands never breaks existing invocations
Flexible argument passing	Unmatched suffixes become command parameters
Predictable resolution	Right-to-left truncation yields deterministic behavior

Summary

• Omarchy's CLI router uses longest-prefix dispatch to resolve ambiguous command input
• Implementation lives in bin/omarchy with documentation in docs/cli-router.md
• The algorithm strips arguments from right to left until finding a registered handler
• Remaining arguments after the match are forwarded to the executed command
• This design enables hierarchical command groups without explicit sub-parser declarations

Frequently Asked Questions

How does Omarchy handle conflicting command prefixes?

The longest-prefix rule eliminates ambiguity automatically. A command registering foo bar takes precedence over foo only when both arguments are present. The router never needs to choose between equal-length prefixes because registration enforces uniqueness.

Can a command receive arguments that look like sub-commands?

Yes. Since the router strips only when no match exists, a command can accept arguments that happen to match other command names. The arguments --delay 2 in the earlier example demonstrate this: they resemble flags but are treated as opaque strings passed to the matched handler.

Where is the command prefix metadata defined?

Prefix declarations appear in agents/skills/command-metadata.md, which documents how each skill registers its accepted argument patterns. The router consumes this metadata at runtime to build its resolution index.

What happens when no prefix matches at all?

Control flows to the top-level omarchy command handler, which typically invokes the default help display or returns a non-zero exit code with usage instructions.

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