Model Router

Route every task to the cheapest Claude model that still gets it right — and cut cost by ~60% vs always using the top model.

The catch it solves: the cheapest model is not the cheapest answer. Underpower a hard task and it fails, you retry on a bigger model, and you've paid twice. This router picks the right tier the first time — and escalates automatically if it's wrong.

• ✅ 100% routing accuracy on a held-out test set
• ✅ ~60% cheaper than always-top
• ✅ Pure Python, stdlib-only — nothing to pip install

---

Requirements

• Python 3.9+
• (optional) the claude CLI — lets the installer auto-register the MCP server

Install

git clone https://github.com/manishk753/claude-model-router.git
cd claude-model-router
./install.sh

Installs the Claude Code skill, registers the MCP server (if claude is on your PATH), and runs a smoke test. Re-running is safe. Restart Claude Code afterward so the tools load.

Want just one piece?

| Command | Installs | |---|---| | ./install.sh | Skill + MCP server (all projects) | | ./install.sh --skill | Skill only | | ./install.sh --mcp-user | MCP server only (all projects) | | ./install.sh --mcp | MCP server only (this project) | | ./install.sh --help | Show help |

Use it

Run the examples below from the repo directory.

1. Command line

python3 -m router "Debug this race condition in our async job queue"

Returns JSON: model, tier, complexity, confidence, rationale, escalate_to.

Force the top tier for high-stakes work:

python3 -m router "Delete inactive users in production" --context '{"critical": true}'

2. Claude Code (skill)

Type /model-router <task>. Claude routes, then uses the returned tier's model — cheap → haiku, mid → sonnet, high → opus, top → fable.

3. MCP server

Exposes one tool: route_task(task, critical?, context_tokens?). The installer registers it for you. To do it by hand from the repo directory:

claude mcp add --scope user model-router -- python3 "$(pwd)/router/mcp_server.py"

Claude Desktop — add to claude_desktop_config.json (use the absolute path to router/mcp_server.py):

{"mcpServers": {"model-router": {
  "command": "python3",
  "args": ["/absolute/path/to/claude-model-router/router/mcp_server.py"]
}}}

4. Python API

pip install anthropic   # only this path needs it

from router.dispatcher import dispatch
response, decision, attempts = dispatch("Debug this race condition: ...")

dispatch() routes, calls the chosen model, and auto-escalates one tier on failure.

Try the eval

python3 eval/run_eval.py     # scores every strategy, prints a table
python3 eval/run_test.py     # held-out set + writes eval/test_report.html

Configure

All model IDs, prices, tier cutoffs, and weights live in config.json — no code changes needed.

⚠️ Model IDs and prices change over time. Verify them against the live API.

Tune: run python3 eval/run_eval.py, read the misroute list, then adjust tier_cutoffs first, weights second, keyword banks last.

How it works

Free deterministic heuristics handle clear cases. A tiny Haiku classifier breaks ties only on ambiguous tasks. A capped escalation path catches the rest. Full decision contract and rules: SKILL.md.