claude-code-autoroute

AutoRoute for Claude Code

AutoRoute is Claude Code model routing built on Claude Code subagents, spreading work across Haiku, Sonnet, and Opus with failure tracking and experimental self-tuning.

Running everything on the top model means it also does your file searches, log reads and boilerplate; hand-written routing rules go stale, and nothing tells you when a cheap model was quietly wrong. AutoRoute lets cheaper models handle routine work, and escalates when they struggle.

What it does

• Routes by tier. The session reads which model it is and hands work down: Haiku finds and reads, Sonnet implements and tests, Opus reviews and debugs, Fable designs UI (ui-designer), the top model otherwise only decides.
• Escalates one rung at a time. An agent that cannot deliver returns a fixed ESCALATE block naming the next rung. Nothing jumps straight to the top model.
• Records failures. Every agent logs a ledger row, and the caller logs a WRONG row when a delegated answer proves wrong.
• Tunes itself, and reverts. A retune agent moves tiers one rung at a time from those ledgers, then verifies its own last move against its baseline.

AutoRoute observes what gets delegated, tracks escalations and known wrong answers, adjusts model tiers from that evidence, and checks whether its own routing changes actually improved things.

Quick install

git clone https://github.com/Bijaykars/claude-code-autoroute
cd claude-code-autoroute
python install.py            # Python 3.9+ on PATH

Restart Claude Code. python install.py --dry-run previews the changes; --uninstall removes them.

By default this installs only the routing block, agents and hooks; your existing CLAUDE.md and coding preferences are kept. --full-claude-md also installs the coding rules. Details, manual steps and what gets backed up: docs/install.md. Optional companion: the Ponytail plugin for a minimal-code discipline; AutoRoute does not require it.

Experimental: as a plugin, without touching your CLAUDE.md: /plugin marketplace add Bijaykars/claude-code-autoroute then /plugin install autoroute. Newer and less exercised than install.py; see docs/plugin.md.

How it routes

Small, self-contained tasks with complete context stay in the main session; starting an agent has overhead.

See docs/escalation.md for the escalation contract and docs/self-tuning.md for the ledger, thresholds and rollback. Common questions: docs/faq.md.

Commands

python autoroute.py <command> (or /autoroute <command> under the plugin) reads .claude/autoroute/ledger.jsonl, the hook-captured ledger: status — per-agent runs/escalated/wrong and RETUNE DUE flags · stats — agent x model table of runs, success %, tokens, duration · why <agent> [words...] — per-model record, "insufficient data" below N=10, never a recommendation below it · wrong <agent_id|last> "<why>" — mark a delegated result wrong · off / on — the global kill switch · mark-retune <agent> "<note>" — the marker retune writes instead of a markdown line. Details: docs/plugin.md.

Cost

Cost, in theory

List prices per million tokens from the Claude API docs (2026-10-09): Fable 5.1 $10 in / $50 out, Opus 5.5 $4 / $20, Sonnet 5.5 $2 / $10, Haiku 5.5 $0.10 / $0.50 for prompts up to 100K tokens ($0.50 / $2.50 above, each request priced on its own). At an 80/20 input/output mix that is a blended $18 / $7.20 / $3.60 / $0.18 per million (Haiku at the up-to-100K rate), so Opus is about 40% of Fable, Sonnet a fifth, Haiku a hundredth. Sonnet 5.5 (2026-09-28) held Sonnet 5's price, while Anthropic claims up to 30% lower cost per task from fewer tokens, so the Sonnet tier may be cheaper in practice without the table changing.

Why only four models

The ladder only ever routes to Haiku 5.5, Sonnet 5.5, or Opus 5.5, plus Fable 5.1 for ui-designer and whichever model runs the orchestrating session. Older siblings are same price or dearer for less capability: Sonnet 4.6 lists at $3/$15, 50% more than Sonnet 5.5's $2/$10, and Opus 5 itself is now legacy, priced at $5/$25 against Opus 5.5's $4/$20 for less capability — the same trap as the 4.x releases. Sonnet 5 is likewise legacy at exactly Sonnet 5.5's price, so it is dominated on age alone rather than on price. Haiku 4.5 is legacy too: it lists at $1/$5, ten times Haiku 5.5's $0.10/$0.50, with no effort control. Fable prices 2.5x Opus per token for an essentially equal coding and design score, so it is a judgment seat, not a worker an agent gets routed to. The exception is ui-designer, which runs on Fable 5.1 by the author's preference; Design Arena's Website category currently puts Opus 5.5 ahead, so change its model: to opus for the cheaper default. And prompt caches are scoped per model, so every extra model added to the rotation splits cache reuse and pays for it twice; Opus 5.5 cache reads are 5% of base input rather than the usual 10%, which makes staying on one model pay off a little more. On Claude Platform on AWS, Amazon Bedrock, Google Cloud and Microsoft Foundry the sonnet alias resolves to an older Sonnet (4.6 or 4.5), and on Microsoft Foundry opus also resolves to Opus 4.6, so users there should pin full model IDs; see docs/faq.md.

Effort matters more than model on 5.5. Artificial Analysis (2026-10, independent) measured Sonnet 5.5 at xhigh at $2.01 per task for 52 points, while Opus 5.5 at high costs $1.82 for 54. Past high, the cheaper Sonnet tier is therefore the dearer choice, which is why a Sonnet agent's effort stops at high and its next step is Opus at medium. Haiku 5.5 at xhigh reaches 41 points for $0.12 on the same general index, tying Sonnet 5.5 at medium, but it trails Sonnet on coding (Terminal-Bench 39% vs 71%), so Haiku's rungs stay find/read only. This is an independent measurement on a general intelligence index, not a coding-only benchmark.

The saving depends entirely on how much of a session is lookup and mechanical work versus judgment. An illustrative split for a typical coding session, 1M delegated tokens:

Under that split the delegated work costs about 30% of the all-top-model price. Most of the gap is the UI row: with ui-designer switched to model: opus, the same split costs $3.83, about a fifth. Move the split toward judgment and the saving shrinks; move it toward lookups and it grows. Measure your own split from the ledgers before quoting a number, and remember the orchestrating session itself still runs on the top model. Subscription usage is a different accounting from API cost; keep them separate.

Estimated API cost from reported token usage, one working day

One session on the author's own project (a Node/Express trading-signals codebase with a vanilla-JS frontend), 2026-09-14, using the token counts each subagent reported on completion. Twenty-two delegated tasks: repo searches, log digests, a root-cause bug fix, a new UI tab, a code review, two research batteries, a theme pass, a web research task. The dollar figures assume an 80/20 input/output split because the reported counts were totals, not separate input/output/cache numbers; real input/output/cache accounting is on the roadmap.

The delegated work cost 28% of what the same tokens would have cost on the top model. The split that day was 17% Haiku, 65% Sonnet, 10% Opus, 8% Fable by tokens, so it was heavier on Sonnet than the illustrative split above and lighter on lookups.

What it excludes: the orchestrating session's own tokens (the part the top model was actually paid for), prompt-cache discounts, retries, and the possibility that a stronger model would have finished some tasks in fewer tokens. One day, one project, one operator. It is the order of magnitude, not a benchmark; the reproducible comparison is on the roadmap. This measurement predates Opus 5.5 (released 2026-09-22); the same UI work would cost less today, so the $2.48 figure is a floor on the saving, not a current quote. It also predates Sonnet 5.5 (2026-09-28), and since Sonnet carried 65% of that day's routed tokens, Anthropic's claimed cost-per-task reduction, if it holds on this workload, would lower the routed figure further. It predates Haiku 5.5 (2026-10-07) too, which prices Haiku at a tenth of the figure used here.

What is inside

Status

• Running on one project since 2026-09-14; the ledgers have a handful of rows, and one working day has been measured — neither is a benchmark.
• The retune thresholds are starting heuristics, and the file that defines them says so.
• Since 0.3, the ledger is captured by hooks (hooks/ledger.py), not written by hand: every delegation gets a row automatically. outcome: "resolved" means the subagent finished without escalating — it is NOT a correctness signal; run autoroute.py wrong/ok to record whether a result was actually checked. Agent-written .claude/agent-memory/<agent>/MEMORY.md rows are kept only as a fallback for a project or agent where the JSONL ledger has no rows yet.

Roadmap

Done in 0.3: plugin packaging (docs/plugin.md, experimental), the hook-captured ledger (hooks/ledger.py), and python autoroute.py status | stats | why | wrong | off | on | mark-retune.

"Learns what works" is a v0.4 claim, once correctness signals come from tests/lint/build instead of only a human wrong/ok call; today AutoRoute observes what gets delegated and tracks escalations and known wrong answers.

• v0.4: /autoroute redo — re-run the last delegation one rung up automatically; correctness signals sourced from tests/lint/build instead of only a human wrong/ok call; task-shape tagging on ledger rows.
• v0.5: cost-to-success routing by task shape, once every model cell for an agent reaches N ≥ 10 — with the caveat that escalated samples are selection-biased (Opus only ever sees the tasks Sonnet already failed), so adjacent tiers must be compared on matched task shapes, not raw success rates.
• The small reproducible comparison ("benchmark") described above is unchanged and still on the roadmap: ordinary Claude Code, fixed model assignments, routing with retuning — task success, total cost including the main session and delegation overhead, elapsed time, retries.

Credits

The "think before coding / simplicity first / surgical changes / goal-driven execution" sections of the full CLAUDE.md adapt multica-ai/andrej-karpathy-skills (a community distillation, not affiliated with Andrej Karpathy). The ladder paraphrases DietrichGebert/ponytail. The routing, escalation contract, ledgers, retune loop and hooks are this repo's own.

License

MIT.