bshea-1/Routed

**The Universal Local Router for Agent Skills**
Live Demo | Overview | Architecture | Empirical Tuning | Installation | Quick Start | Comparison | Environments | MCP & Local Models | CLI | FAQ | Star History | License
> [!TIP]
> Download standalone installers directly from GitHub Releases: RoutedSetup.exe (Windows), RoutedSetup.pkg (macOS), and RoutedSetup.deb (Linux).
---
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:
$$\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:
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.
| Metric | Factory Baseline (v1.3) | Empirically Tuned (v1.5) | Delta |
| :--- | :--- | :--- | :--- |
| **Scoring Weights** | 50% Sem / 35% BM25 / 10% Exact / 5% Meta | 43% Sem / 50% BM25 / 7% Exact / 0% Meta | +15% Lexical Contrast |
| **Out-of-Fold Top-1 Accuracy** | 40.0% | **45.6%** | **+5.6%** |
| **Out-of-Fold Top-3 Recall** | 55.6% | **63.3%** | **+7.7%** |
| **Mean Generalization Gap** | N/A | **2.6%** ($\pm 17.7\%$) | Proven Generalization |