Content
# 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
```bash
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
```bash
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:
```bash
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:
```bash
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`):
```json
{"mcpServers": {"model-router": {
"command": "python3",
"args": ["/absolute/path/to/claude-model-router/router/mcp_server.py"]
}}}
```
### 4. Python API
```bash
pip install anthropic # only this path needs it
```
```python
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
```bash
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](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](SKILL.md).
