Routed README

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.
• Empirical Hyperparameter Tuning: Zero magic numbers. Built-in parameter grid search and Stratified 5-Fold Cross-Validation (routed tune) empirically optimize scoring weights with a proven 2.6% generalization gap.
• Adversarial Precision Floor: Grounded semantic gating and calibrated 0.35 confidence floor guarantee zero false activations on gibberish or non-coding prompts.
• Negation Intent and Framework Penalty: Automatically isolates positive intent, suppresses negated skills, and penalizes unprompted framework specializations.
• Model Context Protocol (MCP) Server: Run Routed via routed mcp to eliminate context pollution in LM Studio, Cursor, Claude Desktop, Windsurf, Continue, and Cline.
• 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 an empirically validated 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 (45%)"]
        Semantic["Dense Vector Embeddings (45%)"]
        Meta["Adaptive History & Decay (0-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} = W_{\text{sem}} \cdot \text{Semantic} + W_{\text{bm25}} \cdot \text{BM25} + W_{\text{exact}} \cdot \text{Exact} + W_{\text{history}} \cdot \text{Metadata}$$

Empirical Parameter Tuning

Starting in v1.5.0, Routed eliminates arbitrary "magic numbers" by incorporating an empirical hyperparameter optimization engine:

routed tune --folds 5 --apply

Stratified K-Fold Cross-Validation

To ensure scoring weights generalize robustly to unseen prompts rather than overfitting to synthetic queries, routed tune:

1. Precomputes Retrieval Signals: Caches lexical (BM25), exact, and dense vector signals in an in-memory matrix, allowing 1,000+ candidate parameter configurations to evaluate in milliseconds.
2. Stratifies 5 Folds: Splits representative benchmark cases across 9 distinct categories (exact-match, synonym, technical-jargon, abbreviation, indirect-intent, multilingual, multi-skill, domain-specific, no-skill).
3. Optimizes on Training Splits: Sweeps the weight simplex ($\sum W = 1.0$) with step size 0.05 and confidence thresholds to maximize composite Top-1 accuracy, Top-3 recall, and No-Skill precision.
4. Validates Out-of-Fold (OOF): Evaluates discovered weights against held-out validation queries, computing the Generalization Gap ($\text{Train} - \text{Val}$) and standard deviation across folds.

Tuned weights are persisted directly in the local SQLite index.db. All subsequent routed route operations automatically execute with the empirical weights. You can reset to baseline at any time with routed tune --reset.

Dual Evaluation Framework (FAR vs FDR)

Routed evaluates router reliability using dual opposing boundary metrics across 190 evaluation cases (including 50 subtle boundary programming queries and 50 adversarial traps):

• False Accept Rate (FAR): Percentage of no-skill prompts (nonsense strings, recipes, general conversation, or negated skills) that mistakenly trigger a skill. Lower is better (0.0% in v1.6.5).
• False Decline Rate (FDR): Percentage of real, subtle programming requests dropped because a confidence floor was set too high. Lower is better (1.5% in v1.6.5).

Grounded Dynamic Confidence Floor

A single fixed confidence floor creates a false trade-off: raising the floor eliminates gibberish but drops real programming requests that sit near the boundary. Routed resolves this with a grounded dynamic floor:

• Anchored queries (queries with lexical/BM25 overlap or exact tag/keyword match): evaluated with an anchored floor of 0.28, preserving recall and minimizing False Declines.
• Unanchored queries (zero lexical overlap, relying solely on dense embedding space): evaluated with a strict floor of 0.40, suppressing noise and eliminating False Accepts.

Reproduce and Benchmark Locally

The benchmark suite is open, deterministic, and runnable locally:

# Run full benchmark via CLI
routed benchmark

# Output machine-readable metrics JSON
routed benchmark --json

# Or clone the repository and run via npm
git clone https://github.com/BrianShea/routed.git
cd routed
npm install
npm run build
npm run benchmark

The benchmark dataset definition is located at packages/core/src/benchmark/dataset.ts. Custom benchmark datasets can be evaluated using routed benchmark --dataset <path>.

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, Cline). 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 / Cline

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
  tune                Run parameter grid search and K-fold CV to optimize scoring weights
  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

Star History

License

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

See LICENSE for full details.