Routed

The Universal Local Router for Agent Skills

Live Demo | Overview | Architecture | Installation | Quick Start | Comparison | Environments | MCP & Local Models | CLI | FAQ | Star History | License

Overview

Routed is a universal, local, zero-token router for Agent Skills across AI coding environments. It automatically scans, indexes, and routes coding prompts to the most relevant skill using a local hybrid search engine combining Okapi BM25, exact matching, and local dense semantic embeddings.

• Zero Token Cost: Eliminates costly LLM routing calls (saving 1,000+ prompt tokens per interaction).

• Sub-20ms Latency: Local CPU-evaluated hybrid search responds instantly without network roundtrips.

• Model Context Protocol (MCP) Server: Run Routed via routed mcp to eliminate context pollution in LM Studio, Cursor, Claude Desktop, Windsurf, and Continue.

• Native Multilingual Understanding: Understands German, Spanish, French, Japanese, and 100+ languages natively, automatically handling compound words without language switches.

• Native Auto-Updater: Automatic version checks and seamless in-place upgrades via routed update.

• Self-Healing Host Reconciliation: Unified diagnostics and adapter repair via routed doctor --fix.

• Privacy First: Prompt routing is executed 100% locally; no user queries leave your machine.

• Multi-Skill Dispatch: Decomposes compound prompts and activates multiple skills simultaneously.

Architecture

Routed evaluates queries using a multi-tier hybrid scoring pipeline running entirely on local CPU:

flowchart LR
    UserPrompt["User Prompt (/route)"] --> Engine["Routed Core Engine"]

    subgraph Engine["Hybrid Scoring Pipeline (Local CPU)"]
        Exact["Exact / Alias Match (10%)"]
        BM25["Okapi BM25 Lexical (35%)"]
        Semantic["Dense Vector Embeddings (50%)"]
        Meta["Adaptive History & Decay (5-25%)"]
    end

    Exact --> Scorer["Composite Hybrid Scorer"]
    BM25 --> Scorer
    Semantic --> Scorer
    Meta --> Scorer

    Scorer --> Selection["Top Skill(s) Resolved (< 20ms)"]
    Selection --> Agent["AI Host Agent (Antigravity / Claude / Cursor / OpenCode / Codex)"]

$$\text{Composite Score} = 0.50 \cdot \text{Semantic} + 0.35 \cdot \text{BM25} + 0.10 \cdot \text{Exact} + W_{\text{history}} \cdot \text{Metadata}$$

Comparison

Installation

Instant Test (Zero-Install via npx)

Test Routed immediately in any project without downloading an installer:

npx routed route "refactor auth service and add unit tests" --explain

Or run the interactive setup wizard directly:

npx routed setup

To install globally via npm:

npm install -g routed

Standalone Installers

For permanent, system-level local installation across all AI coding environments:

Build from Source

git clone https://github.com/bshea-1/Routed.git
cd Routed
npm install
npm run build
npm run setup

Quick Start

1. Interactive Setup Wizard

Run the setup wizard to detect installed AI coding tools and configure /route adapters:

routed setup

2. Discover & Index Skills

Scan local directories and build the hybrid index:

routed scan
routed skills

3. Route Prompts

Inside your AI agent chat (Antigravity, OpenCode, Claude Code, Cursor, Codex):

/route write a unit test for my authentication service using TDD

Or from your terminal:

routed route "audit accessibility and fix memory leaks" --explain

4. Diagnostics

Verify system health, SQLite indices, and embedding models:

routed doctor

Supported Environments

Model Context Protocol (MCP) & Local Models

Routed can be attached as a standard MCP server to any compatible host (LM Studio, Cursor, Claude Desktop, Windsurf, Continue). Instead of dumping 50+ tool schemas into your model context and exhausting VRAM, the host model only calls the route_skill tool. Routed evaluates the prompt on local CPU in sub-20ms and returns only the matched skill manifests.

Add to Claude Desktop / Cursor / LM Studio

Add the following snippet to your host configuration file:

{
  "mcpServers": {
    "routed": {
      "command": "routed",
      "args": ["mcp"]
    }
  }
}

Direct Ollama Integration

Generate Ollama tool schemas for /api/chat function calling:

routed ollama tools

Route a prompt and generate a ready-to-run Ollama API payload:

routed ollama run --prompt "build a neural network in pytorch" --model llama3.2

Hermes Agent Integration

Generate tool schemas (OpenAI JSON or Nous Hermes XML) for Hermes agents:

# OpenAI-compatible JSON schema
routed hermes schema

# Nous Hermes XML schema
routed hermes schema --xml

# System prompt guidance snippet
routed hermes prompt

Route a prompt and get ready-to-inject instructions:

routed hermes route "refactor auth service"

Agent Harness Safety with HOL Guard

Routed integrates directly with HOL Guard (command.routed) to ensure safe automated execution inside agent harnesses. HOL Guard intercepts and flags state-modifying operations (routed doctor --fix, routed adapters install, routed adapters uninstall, and routed update) for pre-action human review, while allowing routine routing (routed route), diagnostics (routed doctor), and update checks (routed update --check) to execute without interruption.

CLI Reference

Usage:
  routed <command> [arguments] [options]

Commands:
  setup               Run the interactive setup wizard
  update              Check for updates and automatically upgrade Routed (--check to inspect)
  mcp                 Start Model Context Protocol (MCP) server for LM Studio, Cursor, Claude
  ollama <subcommand> Ollama tool schemas, Modelfiles, and direct route integration
  hermes <subcommand> Hermes agent schemas (JSON/XML), prompts, and direct route integration
  route "<prompt>"    Find the best matching Agent Skill(s) for a prompt
  scan                Scan supported AI environments and update index
  skills              List all discovered and indexed skills
  adapters            Manage /route adapters across AI coding tools
  doctor              Run system, database, and model diagnostics (--fix to repair)
  reindex             Incrementally re-index and re-embed installed skills
  watch               Continuously monitor skill directories for file changes
  feedback            Manage local routing preferences and corrections
  uninstall           Safely uninstall Routed and remove adapters (--dry-run available)
  status              Display current system status and detected environments
  benchmark           Run routing benchmark suite and measure accuracy and latency
  version             Print version information
  help                Display help screen

FAQ

Routed follows an idempotent desired-state convergence model with zero blast radius. Each host adapter runs in an isolated boundary: if Cursor installs successfully but Claude Code fails (for example, due to a file lock or directory permission), Cursor is preserved and remains fully functional. Running routed doctor --fix or routed adapters install automatically detects and reconciles any missing adapters in a single command.

Routed runs quantized ONNX dense embedding models (Snowflake Arctic Embed S / all-MiniLM-L6-v2) directly on local CPU alongside Okapi BM25. Vector similarity and text indices are cached in a local SQLite database, requiring no internet connection or cloud tokens.

When a prompt contains compound intents or conjunctions (such as "and", "with", "as well as"), Routed decomposes the prompt into sub-clauses, scores candidates across all clauses, and returns all matching skills in selectedSkills for joint agent activation.

No. Benchmark execution times average under 20 milliseconds on local CPU, making routing practically instantaneous compared to remote cloud roundtrips (1,200ms to 3,500ms).

Routed stores its index and database files in standard platform directories:

• macOS: ~/Library/Application Support/Routed

• Linux: ~/.local/share/routed

• Windows: %LOCALAPPDATA%\Routed

Star History

License

MIT License. Copyright (c) 2026 bshea-1.

See LICENSE for full details.