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

> Discover Omarchy's longest-prefix dispatch algorithm. Learn how the CLI router intelligently matches your commands for efficient execution. Optimize your terminal workflow today.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: internals
- Published: 2026-09-06

---

**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`](https://github.com/omacom/omarchy/blob/main/agents/skills/command-metadata.md), specifying how groups declare their accepted argument patterns.

Documented behavior appears in [`docs/cli-router.md`](https://github.com/omacom/omarchy/blob/main/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)

```bash
omarchy capture-screenshot

```

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

### Partial Match with Argument Passing

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

```bash
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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/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.