Model Routing
Claude model choice is the biggest cost lever in Claude Code. Match the model to the work.
Decision matrix
| Task type | Model | Why |
|---|---|---|
| Long-horizon autonomous run (overnight build, large migration end-to-end) | Fable | Sustains multi-hour agentic work and async subagent fleets that stall lesser models |
| Hardest unsolved problem (Opus failed or would need many retries) | Fable | Highest reasoning ceiling; one Fable pass can beat several Opus retries |
| Architecture decision | Opus | Multi-step reasoning; hidden-cost detection |
| Root-cause debugging (hard) | Opus | Hypothesis trees, multi-source evidence |
| Security review | Opus | Risk sensitivity; knowledge of OWASP/CWE |
| Feature implementation | Sonnet | Standard generation; good reasoning |
| Code review (routine PR) | Sonnet | Fast; catches most issues |
| Test writing | Sonnet | Pattern-based |
| Research / docs lookup | Haiku | Fast; cheap; sufficient for retrieval |
| Bulk file edits (rename, reformat) | Haiku | Mechanical work |
| Dependency audit | Haiku | Running commands, parsing output |
| Simple Q&A | Haiku | One-shot factual answers |
Cost table (approximate, check cc_docs_model_recommend for current)
| Model | Alias / ID | Input $/M | Output $/M | Relative |
|---|---|---|---|---|
| Fable 5 | fable / claude-fable-5 | $10 | $50 | 3.3× |
| Opus 4.8 | opus / claude-opus-4-8 | $5 | $25 | 1.7× |
| Sonnet 5 | sonnet / claude-sonnet-5 | $3 | $15 | 1× |
| Haiku 4.5 | haiku / claude-haiku-4-5-20251001 | $1 | $5 | 0.33× |
Output tokens are the dominant cost in most Claude Code sessions. Two caveats on Fable 5: its new tokenizer produces ~30% more tokens for the same content (so the effective gap vs Opus is wider than the per-token price), and turns run longer. Use it where the capability ceiling matters, not as a default. Sonnet 5 uses the same new tokenizer (~30% more tokens than Sonnet 4.6 for identical content) and launched with introductory pricing ($2/$10 per MTok through 2026-08-31) — the table shows the sticker price.
Aliases auto-resolve to the latest generation — prefer fable/opus/sonnet/haiku over pinned IDs so a model refresh doesn't strand your config. Use opusplan for Opus-reasoning + Sonnet-execution, or best for "most capable available". Extended 1M-token context: opus[1m] / sonnet[1m] (Fable 5 is 1M by default; claude-fable-5[1m] is the long-context ID form).
Fast mode (/fast in-session, --fast at launch) keeps you on Opus (4.6/4.7/4.8) but optimizes for faster output — it does not downgrade to a smaller model. Toggle it when you want Opus-level reasoning without the usual latency. Not available on Fable 5.
Effort levels scale reasoning depth independently of model: low · medium · high · xhigh · max (Opus 4.7/4.8, Sonnet 5, and Fable 5 support xhigh). Set via /effort, --effort <level>, or effort: in skill/agent frontmatter — cheaper than jumping a model tier when you just need deeper thinking. On Fable 5 thinking is always on and effort is the only depth control — and even low effort on Fable often matches or beats max on prior models, so sweep downward for routine work.
Model cascading
The high-leverage pattern: start with a cheap model for planning, delegate implementation to cheap, reserve Opus for review gates.
| Phase | Model |
|---|---|
| Plan mode (Shift+Tab) | Opus (Fable for the hardest/longest-horizon plans) |
| Implementation | Sonnet |
| Subagent research | Haiku |
| Code review gate | Opus |
| Final sign-off | Opus |
| Overnight / multi-hour autonomous run | Fable (orchestrator only; workers stay on Sonnet) |
Net effect: most tokens are on Sonnet/Haiku; Opus tokens are where they matter most; Fable tokens are reserved for the rare runs that justify the tier.
Budget planning
For a task estimated at N turns:
- Rough floor: 2k input + 2k output per turn = 4k tokens.
- Sonnet cost: 4k × $3/M = $0.012 per turn.
- 20-turn session on Sonnet: ~$0.24.
- Add 3 Opus review passes: +$0.45.
- Total: ~$0.70.
Use cc_docs_model_recommend(task, budget) to get a specific recommendation with cost projection.
Downgrade/upgrade triggers
Downgrade to Haiku when:
- Doing pure retrieval (grep results, file reads).
- Running a known command and parsing output.
- Rate-limited on Sonnet budget.
Upgrade to Opus when:
- Sonnet gets it wrong twice on the same subtask.
- Task is security-critical.
- Stakeholder cost of error is ≥ days of engineer time.
- You're designing something new (vs. implementing something known).
Upgrade to Fable when:
- Opus has failed (or would clearly need multiple retries) on the same problem.
- The run is long-horizon and autonomous — overnight builds, end-to-end migrations, multi-wave orchestration where mid-run drift is the failure mode.
- You're coordinating a fleet of long-lived async subagents and need the orchestrator to stay coherent for hours.
- Don't route security-scanning/offensive-security analysis to Fable — its cyber safety classifiers can refuse (
refusalstop reason); keep that on Opus.
/plan mode
Shift+Tab toggles plan mode — uses Opus to think deeper without producing code. Use for:
- New feature scoping
- Debugging a tough bug before trying fixes
- Architecture choice before committing
Don't use plan mode for: known patterns, mechanical work, small tweaks.
MCP delegation
| Need | Tool |
|---|---|
| Model recommendation for a task | cc_docs_model_recommend(task, budget?) |
| Compare two model choices | cc_docs_compare(["opus", "sonnet"]) |
| Check cost of an autonomy profile | cc_kb_autonomy_profile(profile) |
Anti-patterns
- Defaulting to Opus everywhere → ~1.7× cost, rarely 1.7× value on routine work.
- Defaulting to Fable everywhere → 3.3× price and ~30% more tokens per task; the tier pays off only above Opus's ceiling.
- Haiku on hard tasks → gets it wrong, then you re-run on Opus = wasted double cost.
- Ignoring
/planon new work → code-first on unfamiliar problems wastes tokens. - Not estimating budget → costs creep; you notice on the monthly bill.