model-routing

model-routing

Tiered model routing for Claude Code token economy: the strongest model thinks, cheaper models grind.

Planning and architecture stay in your main session on the best model you have. Implementation, review, and test runs get delegated to subagents on cheaper tiers - and the raw output (test logs, file reads) never enters your main session context, which is where most tokens actually die.

Routing tunes two knobs, not one: which model handles a task and how hard it thinks (reasoning effort). A strong model at low effort often beats a weaker model straining at high effort, for a fraction of the cost - so cheap, well-scoped work runs at low effort and only genuinely hard reasoning gets high or above. Each bundled agent pins its effort in frontmatter, overriding the session setting. When a subagent gets stuck on the approach rather than a missing fact, it escalates back to the main session for a decision instead of thrashing.

Everything stays inside Anthropic models. No proxy, no third-party gateway, nothing extra in the request path.

When this saves you money, and when it does not

Read this before installing, because the honest answer has two halves and evals/ measured both.

A subagent is not free. It starts with an empty context, so everything it reads is a cache write, while your main session pays cache read - 12.5x cheaper, 50x on Fable 5.1 and Mythos 5.1 - for what it already has. Delegation converts cheap re-reads into expensive first-reads, and that bill lands whether or not this plugin is installed.

What the plugin changes is the price per token, not that penalty. So:

Your situation	What this plugin does
You already dispatch subagents - Superpowers, workflows, any delegation-heavy practice	Saves, by roughly a sixth. $1.68 with the tier routed down, against $2.01 for the same subagent work at your session's tier
You work mostly in one session and rarely delegate	Costs, by roughly a fifth. $1.36 doing it inline against $1.68 routed

One workload, three runs an arm, on a four-turn session that never had to compact - so read the direction as solid and the exact percentage as not. The $2.01 is the measured subagent tokens repriced at the session tier, not a run of its own; the pricing model reproduces the billed figure it was checked against to the cent, but a live top-tier subagent might well read less and narrow the gap.

An unpinned subagent inherits the session model, so on an opus session Superpowers dispatches opus subagents by default. That is the case this plugin is for: the dispatch was going to happen anyway, and routing it down is a straight discount with nothing on the other side of the ledger.

Note what the surcharge is and is not. The plugin costs about 1.6k tokens a session to carry - ~700 for the skill and agent listings, plus a ~900-token routing anchor at session start - which is a couple of cents against sessions billing $1.40 to $2.00. The listing figure comes from claude plugin details model-routing, and its output is committed under evals/evidence/ with the CLI version that produced it, since it moves whenever a component is added. That is not where the 23% comes from. It comes from dispatches happening that otherwise would not have: on the same question the plugin arm delegated in 3 runs of 3 and the plugin-free arm in 0 of 3. Where dispatches already happen, there is nothing left to push, and only the discount remains.

If you rarely delegate, install it for the context headroom or not at all. The expensive tier does read measurably less either way - opus input volume down about 25% on the same test, and opus spend with it by 14% - but headroom is a different thing from a smaller bill, and this README used to blur the two.

(The A/B that would replace the repricing with a run is still blocked, for the reason written down in evals/forced-dispatch-tier/NOTES.md.)

Quick links: Does this save money? | Overview | Example | Install | Getting started | Usage | Tiers | Settings | Workflows | Stats | Pin overrides

What's inside

Component	Model	Effort	Purpose
agents/scout.md	sonnet	low	Read-only codebase exploration: conclusions and file:line refs come back, file dumps stay out.
agents/surveyor.md	haiku	low	Read-only breadth: enumerate, list, trace a chain end to end. Measured correct on the cheap tier where scout's judgement work is not.
agents/test-runner.md	haiku	low	Run tests/builds/linters, report failures compactly. Never fixes anything.
agents/e2e-runner.md	sonnet	medium	Drive Playwright/E2E scenarios, interpret failures (product bug vs test bug vs flake).
agents/implementer.md	sonnet	medium	Implement one well-defined task from an approved plan. Verifies its own work. Dispatch with model=opus for multi-file/architectural/subtle work (model=<session model> on a Fable 5.1 or Mythos 5.1 session).
agents/reviewer.md	opus	high	Review a diff for correctness bugs, ranked by severity.
agents/verifier.md	haiku	low	Cheap gate on a subagent's diff: does it match the task (scope, completeness, obvious breakage)? Not a code review.
skills/model-routing/	-	-	The routing table and delegation rules Claude follows when deciding where work goes.
hooks/routing-anchor.md	-	-	Short routing anchor auto-injected at session start - zero config.
hooks/dispatch-counter.mjs	-	-	Logs every Agent dispatch; stats/report/tokens modes measure what stayed off the session model.
commands/stats.md	-	-	/model-routing:stats - dispatch + token-volume report in the chat.

Example

A typical feature session on a strong main model (Opus/Fable):

Implement tasks 1-2 from the plan, then run the unit tests.

Without the plugin everything happens in the main session: it reads a dozen files, writes code, and dumps the full test log into your context. Thousands of expensive tokens spent on mechanics.

With the plugin:

Main session (strong model, plans and coordinates):
  dispatches implementer (sonnet) with two self-contained tasks

    implementer: Changed OrderService.cs (null-payload guard) and
    OrderServiceTests.cs (3 new tests). Build OK, 214/214 unit
    tests pass.

  dispatches test-runner (haiku) for the final check

    test-runner: PASS. 214/214, 0 skipped.
    Command: dotnet test src/Orders.Tests.csproj

  reports back to you.

The file reads, diffs, and raw test logs stayed inside the subagents. Your expensive main-session context grew by two short reports.

What that looks like in tokens

Snapshot: 2026-08-02, measured with v0.13.0 - the author's live workload over the preceding 7 days, via dispatch-counter.mjs tokens, ... tokens --session fable and ... report --session fable. A fixed snapshot, not a live figure: the rolling window moves daily and your split depends on your task mix - re-measure your own with the same commands.

Read the scope before the numbers, because there are two of them and they are easy to mix up.

	All sessions	Fable-default sessions (the charts below)
Main-session volume, not routable	6.85B	1.08B across 33 sessions
Subagent volume, routable	1.77B	285.2M across 103 agents
Subagents as a share of the total	21% of 8.64B	21% of 1.36B
Ran below the session tier	33%	99%

Two things follow. First, the main session is not in any chart here and never can be: its model is fixed for the turn, so no routing decision moves it. Routing governs about a fifth of what was actually spent, and the charts describe how well it governs that fifth - not how much of the bill it removes. Second, the 99% belongs to the fable-scoped column: on an opus-default session an opus subagent is not a step down, so there is little room to route anywhere, which is most of the gap between 99% and 33%. Both figures are true, and tokens now prints them together so the flattering one is never read alone.

The charts below take the fable-scoped column. In it, 98% of dispatches (82 of 84) and 283.1M of 285.2M tokens ran below the session tier. Without routing every subagent inherits the session model, so the whole 285.2M would bill at Fable prices; with routing 2.1M did:

xychart-beta
    title "Subagent tokens billed at the top (Fable) tier - 7d, fable-default sessions"
    x-axis ["without routing (inherits session model)", "with model-routing"]
    y-axis "millions of tokens" 0 --> 300
    bar [285.2, 2.1]

That left bar is an upper bound, not a measurement. It assumes every subagent would otherwise inherit the session model, which is the documented default for an UNPINNED agent - but pinned agents exist independently of this plugin. Other installed plugins ship their own pinned agents, and Claude Code's built-in Explore ran haiku before Claude Code 2.1.198 (since then it inherits the session model, capped at opus). Some of this volume would have run cheaply with model-routing uninstalled; how much was not measured, so read the bar as the ceiling of what routing can be credited with rather than the amount it saved.

Attribution over the same week, across all 266 dispatches, 199 of which ran below their session tier:

Mechanism	Dispatches	What it means
Agent frontmatter pins shipped by this plugin	68	Automatic. The agent file names the tier, so it fires whether or not any routing rule is followed
An explicit model= on the dispatch	127	Behavioural. This is the routing rules being applied, and nothing enforces them
Claude Code's built-in Explore	4	Not this plugin at all

The honest reading: the automatic half is fully attributable, the behavioural half depends on the session actually following the anchor, and these numbers have no control group of their own - this is the author's own workload measured with the author's own tool, with no before-install baseline. CLAUDE_CODE_SUBAGENT_MODEL was not set in this window, which the report would otherwise have annotated per row.

For the behavioural half there is now a control group, just a much smaller one: evals/ runs the same question with and without the plugin loaded. The behavioural claim holds - on a codebase question the plugin arm delegated to scout in 3 of 3 runs and the plugin-free arm in 0 of 3, grepping inline despite having Explore available.

The money is a more interesting answer than "it saves". On a wide-reading question across a four-turn session, the expensive tier drops either way - opus spend down 14%, its input volume down about 25% - but the shipped configuration ends up 23% more expensive in total than not having the plugin at all, because a fresh subagent pays cache write for everything it reads while a main session pays cache read, 12.5x cheaper (50x on Fable 5.1 and Mythos 5.1), for what it already has. So what this plugin reliably buys is room in the expensive model's context, not a smaller bill; where the bill also falls is a narrower claim, and it depends on the tier.