claude-model-router

Reference implementation of cost-aware model routing for the Claude API — plus a Claude Code hook that stops subagents from silently inheriting your most expensive model.

A cheap Haiku 4.5 call classifies each prompt's complexity; the prompt then executes on the cheapest capable tier. Small, tested, and built around the parts naive routers get wrong.

Why naive Claude routers break

Most routing examples treat model IDs as interchangeable strings. On the Claude 5 family they are not:

Tiers

The keyword-heuristic fallback (used when the classifier call fails) never assigns trivial — misrouting real work to Haiku costs more in retries than the tier saves, so only the classifier may pick it.

Usage

import anthropic
from model_router import run, execute

client = anthropic.Anthropic()

result = run(client, "Refactor the auth module across services")
print(result.route.model, result.route.source)  # claude-fable-5 classifier
print(result.served_by)                          # may be opus-4-8 after a fallback
print(result.text)

Multi-turn: prompt caches are model-scoped, so route once per conversation and reuse the route for follow-ups —

route = result.route
result2 = execute(client, route, full_message_history)

Cost model

1,000 prompts, mixed workload (30% trivial / 40% low / 20% mid / 10% high), list pricing, output token counts held equal across models (conservative — Fable at xhigh thinks longer than smaller models on the same prompt):

26% saved on this mix — and the mix is the whole story: the 10% of prompts that legitimately need Fable dominate the bill. A support-bot-shaped workload (mostly trivial/low) saves 70%+. Rerun with your own shape:

python benchmarks/cost_model.py

This is a pricing calculation, not a live benchmark — it spends no tokens and its assumptions are at the top of the script.

Live benchmark (real tokens, real dollars)

benchmarks/live_bench.py runs a 17-prompt mixed workload through both arms — routed vs. all-Fable — with real API calls, and prices each call from the usage block the API actually returned (by the model that actually served it, which matters after a fallback). Classifier overhead is metered from real Haiku usage, not estimated.

ANTHROPIC_API_KEY=... python benchmarks/live_bench.py --tiers trivial,low  # cheap smoke run
ANTHROPIC_API_KEY=... python benchmarks/live_bench.py --out live_results.md  # full run, ~$2-6

It spends real money (the all-Fable arm at xhigh dominates), refuses to start without a key, and flags every prompt where the classifier's tier disagreed with the expected tier — so you can audit misroutes instead of trusting a single savings number. RoutedResult.usage exposes the same real token counts in your own code.

This is the honest version of the standard methodology: the same cost-quality comparison RouterBench and RouteLLM run offline, at a scale one person can afford to reproduce.

Claude Code hook: stop subagents from burning Fable tokens

Separate deliverable, same philosophy. In Claude Code, subagents inherit the session model by default — run your session on an expensive model and every spawned agent (including greps and file listings) bills at that rate.

hooks/subagent-router.py is a PreToolUse hook that denies any Agent spawn missing an explicit model param. The deny reason carries a routing table, so the session model immediately re-issues the spawn with the cheapest capable tier. Self-correcting, one file, no dependencies.

Install:

cp hooks/subagent-router.py ~/.claude/hooks/

Then add to ~/.claude/settings.json:

"hooks": {
  "PreToolUse": [
    {
      "matcher": "Agent",
      "hooks": [
        {
          "type": "command",
          "command": "python3 ~/.claude/hooks/subagent-router.py"
        }
      ]
    }
  ]
}

New sessions then enforce: unrouted spawn → denied with policy → re-spawned with explicit model (haiku for greps/locates, sonnet for single-file work and reviews, opus for multi-file/hard debugging, session model only for judgment-critical synthesis).

Install

pip install claude-model-router

Or from source:

git clone https://github.com/junoseong/claude-model-router
cd claude-model-router
python3 -m venv .venv && .venv/bin/pip install -e '.[dev]'
.venv/bin/pytest

Notes

• Fable 5 requires 30-day data retention; zero-data-retention orgs get 400s on the high tier — remap high to claude-opus-4-8 in _TIER_ROUTES.
• Sonnet 5 has intro pricing ($2/$10 per MTok) through 2026-08-31; the cost model uses sticker prices ($3/$15).

MIT licensed.