Routed Documentation

Overview and Motivation

Routed is a universal, local-first routing engine designed to eliminate the agent skill context-bloat problem. As AI coding environments (Claude Code, Antigravity, Cursor, Windsurf, LM Studio, Ollama) expand their skill ecosystems, developers frequently install dozens or hundreds of specialized skills.

Preloading all installed skills into the agent's system prompt consumes between 15,000 and 40,000 tokens per interaction. This overhead leads to three severe issues:

• Runaway Token Expenses: Teams pay thousands of dollars per month sending full catalogs of unused skill schemas on every single message turn.
• Degraded Agent Reasoning: Large prompts introduce attention dilution and hallucinated skill activations when unrelated tool definitions overwhelm the model context.
• Increased Latency: Transferring massive prompt payloads over the network adds 1.2 to 3.5 seconds of round-trip latency to every turn.

Routed intercepts prompts locally, evaluates candidate skills in sub-milliseconds on CPU, and injects only the concise specifications required for the current task.

Architecture and Pipeline

Routed evaluates prompts using a deterministic, multi-tier scoring pipeline running entirely on local CPU cycles. The execution flow operates as follows:

User Prompt (/route or terminal)
   |
   +--> 1. Trivial Check (isNoSkill) ---------> Returns 0 skills (clean context)
   |
   +--> 2. Clause Segmentation ---------------> Splits compound prompts ("A and B")
   |
   +--> 3. Parallel Scoring Pipeline:
   |      |-- Exact & Alias Match  (10% weight)
   |      |-- Okapi BM25 Lexical   (35% weight)
   |      |-- Dense Vector Cosine  (50% weight)
   |      \-- Metadata & Tags      (5% weight)
   |
   +--> 4. Composite Scorer ------------------> Normalizes and weights scores
   |
   \--> 5. Multi-Skill Dispatch --------------> Resolves qualifying skills in sub-20ms

By combining dense semantic representations with lexical precision, Routed avoids the blind spots of keyword-only search while maintaining the speed and predictability of local computation.

Hybrid Scoring Formula

Candidate skills are ranked using a composite score calculated from four distinct signals:

CompositeScore = (0.50 * SemanticScore) + (0.35 * BM25Score) + (0.10 * ExactScore) + (0.05 * MetadataScore)

This distribution ensures semantic understanding takes precedence while preserving exact match determinism and lexical filtering.

1. Semantic Embeddings (50% Weight)

Dense semantic vector representation evaluates conceptual similarity using cosine distance. In the native CLI, Routed utilizes quantized local ONNX models (such as Snowflake Arctic Embed S or all-MiniLM-L6-v2) running locally via ONNX Runtime on CPU.

Semantic scoring allows Routed to map user intents to appropriate skills even when the prompt shares zero lexical tokens with the skill name or description:

• Prompt: "audit access controls and examine privilege escalations" → Matches security-audit
• Prompt: "find where my program is consuming runaway ram" → Matches memory-leak-debugging
• Prompt: "write automated unit specs before writing implementation" → Matches tdd

2. Lexical BM25 (35% Weight)

Lexical scoring uses an optimized Okapi BM25 implementation with document length normalization (parameters: k1 = 1.2, b = 0.75). The lexical engine includes two critical preprocessing stages:

Action Stop Word Suppression

Conversational noise and common imperative verbs (such as run, execute, make, write, build, test, please, need, help) are suppressed during indexing and query tokenization. This prevents generic verbs from artificially inflating candidate relevance.

Technical Synonym Decomposition

Routed automatically maps developer shorthand and technical jargon to standard skill terms:

• auth → authentication, authorization, login, oauth
• oom → memory leak, out of memory, heap
• k8s → kubernetes, cluster, deployment
• sec / audit → security, vulnerability, threat
• perf → performance, optimization, latency

3. Exact and Alias Matching (10% Weight)

When a developer explicitly requests a specific skill by name or known alias (for instance: "run 007 audit" or "use tdd approach"), the exact matcher immediately assigns maximum confidence (1.0).

This prevents semantic ambiguity from overriding direct, intentional user commands.

4. Metadata and History (5% Weight)

The metadata scoring layer incorporates secondary attributes, including skill categories, ecosystem tags, tool definitions, and adaptive session history. If a user previously approved a specific skill for related work in the current repository, a subtle historical affinity bonus is applied.

Multi-Skill Resolution

Real-world software prompts often require multiple cooperating skills. Consider the prompt:

"run a security audit and threat modeling for my web application"

Routed decomposes compound sentences containing conjunctions (such as and, with, alongside) into individual task clauses:

1. Clause 1: run a security audit for my web application
2. Clause 2: threat modeling for my web application

Skills scoring above the qualification threshold (multiSkillThreshold = 0.25) are returned in selectedSkills (up to 5 items), allowing the agent to activate all necessary competencies simultaneously.

Trivial Prompt Filtering (isNoSkill)

Not every developer turn requires a specialized skill. Common activities such as fixing syntax errors, checking status, or answering simple programming questions do not warrant skill injection:

• "fix typo in line 42"
• "format this json file"
• "what does this git command do"

For these queries, Routed flags isNoSkill: true and injects 0 skills. The AI agent proceeds with its standard core capabilities, saving prompt tokens and avoiding context distraction.

Architecture Comparison

Supported Environments

Routed automatically configures adapters across leading AI coding tools:

Model Context Protocol (MCP) Integration

Routed can run as an MCP server over standard input/output (stdio). When attached to LM Studio, Cursor, Claude Desktop, or Windsurf, the host environment does not need to load 50+ tool schemas into context.

Instead, the host model invokes the lightweight route_skill tool. Routed evaluates the prompt on CPU in under 20ms and returns only the matching skill specifications.

Configuration Snippet

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

Direct Ollama Integration

For developers using local open-weight models via Ollama, Routed provides direct command integration:

# Generate standard tool schemas for Ollama /api/chat
routed ollama tools

# Route a prompt and produce a ready-to-run Ollama API payload
routed ollama route "audit firestore security rules"

# Generate a customized Modelfile with dynamic skill injection
routed ollama modelfile --skill security-audit

Installation Guide

Zero-Install Evaluation (via npx)

Run Routed instantly in any directory without global installation:

npx routed route "refactor authentication and add unit tests" --explain

Global npm Installation

npm install -g routed

Interactive Setup Wizard

Detect installed AI coding tools and configure local adapters automatically:

routed setup

Standalone Platform Installers

Download precompiled binaries directly from GitHub Releases:

• macOS: RoutedSetup.pkg or RoutedSetup.dmg
• Linux: RoutedSetup.deb or routed-linux-x64.tar.gz
• Windows: RoutedSetup.exe or Install-Routed.ps1

CLI Command Reference

Frequently Asked Questions