Token-Miser
Route every Claude interaction to the cheapest model that can handle it reliably.
This applies to three surfaces:
- Claude Code subagents — set
model param on every Agent tool call
- API calls in code — model selection when writing code that calls Anthropic
- Artifacts — model selection for API calls inside artifacts
Never mention routing decisions to the user unless asked — just apply them.
Scope
| Surface |
Mechanism |
What Token-Miser Does |
| Claude Code subagents |
Agent tool model param (haiku, sonnet, opus) |
Route every subagent to cheapest viable model |
| Claude Code main model |
Recommend /model switch to user |
Flag when current model is overkill or underpowered |
| API calls in code |
Model string in anthropic.messages.create() |
Route to optimal model, escalation wrappers, batching, caching |
| Artifacts |
Model string in browser API calls |
Same as API calls |
Model Tiers (Verified 2026-03-17)
| Tier |
Model |
Agent Param |
API String |
Cost |
Context |
| 1 — Fast/Cheap |
Haiku 4.5 |
haiku |
claude-haiku-4-5-20251001 |
~1x |
200K |
| 2 — Balanced |
Sonnet 4.6 |
sonnet |
claude-sonnet-4-6 |
~3x |
200K |
| 3 — Powerful |
Opus 4.6 |
opus |
claude-opus-4-6 |
~5x |
200K (1M beta) |
See references/model-pricing.md for detailed token pricing.
Claude Code Subagent Routing
This is the primary cost lever. Every Agent tool call accepts an optional
model parameter. Always set it explicitly based on the task.
Subagent Routing Table
| Subagent Task |
Model |
Rationale |
| File search, pattern matching (Explore) |
haiku |
Read-only, deterministic |
| Simple grep/glob delegation |
haiku |
Mechanical search |
| Code review (style, linting) |
haiku |
Pattern matching, checklist |
| Test runner, build validation |
haiku |
Execute + report, no reasoning |
| Research — single focused question |
sonnet |
Needs synthesis |
| Research — broad exploration |
sonnet |
Multi-step, judgment calls |
| Code generation (simple function, boilerplate) |
sonnet |
Needs correctness |
| Code generation (complex, multi-file, architectural) |
opus |
High stakes, needs reasoning |
| Planning / architecture design |
opus |
Open-ended, judgment-heavy |
| Debugging (root cause analysis) |
sonnet |
Start here, escalate if stuck |
| Writing documentation |
haiku |
Templated, low ambiguity |
| Git operations, status checks |
haiku |
Mechanical |
When NOT to downgrade subagents
- Subagent will write code that gets committed — sonnet minimum
- Subagent needs to make judgment calls about ambiguous requirements — sonnet+
- Subagent result feeds directly into user-facing output — match main model tier
- Task previously failed at a lower tier — escalate, don't retry same tier
Main Model Recommendations
| Situation |
Recommendation |
| User on Opus, doing simple file edits / git ops |
Suggest: /model sonnet would save cost |
| User on Haiku, attempting complex multi-file refactor |
Suggest: /model opus recommended |
| User on Sonnet, task is clearly Haiku-tier |
Don't mention — switching friction not worth it |
| User on Sonnet, task is clearly Opus-tier |
Suggest only if quality likely to suffer |
Rule: Only recommend switches when the cost/quality delta is significant.
Sonnet is always an acceptable default.
Freshness Protocol
- Read
references/model-pricing.md header date.
- If <90 days old — use as-is.
- If >90 days old — web-search
Anthropic Claude API pricing before using prices.
- If prices changed — update the reference file.
Skip when: applying routing table (no dollar amounts needed), subagent model
selection (relative tiers don't change with pricing), token efficiency rules.
Routing Decision Framework
Step 1 — Classify the task
| Task Type |
Default Tier |
Notes |
| Simple Q&A, classification, extraction |
1 |
Single-turn, clear answer |
| Summarization (short doc, <20K tokens) |
1 |
|
| Summarization (long doc, >20K tokens) |
2 |
Context pressure |
| Code generation (boilerplate, simple functions) |
1 |
|
| Code generation (complex logic, multi-file) |
2 |
|
| Code debugging / root cause analysis |
2 |
Start here |
| Reasoning / multi-step math / analysis |
2 |
Start here |
| Complex reasoning with ambiguous constraints |
3 |
|
| Long-context document processing (>100K tokens) |
2 |
Watch cost |
| Tool use — simple, single tool |
1 |
|
| Tool use — multi-tool, agentic chains |
2 |
|
| Tool use — autonomous, open-ended agent |
3 |
|
| Structured output / JSON extraction |
1 |
|
| Grading / judging other model outputs |
2 |
Avoid circular bias |
Step 2 — Apply modifiers
Bump up one tier if:
- Output is user-facing AND quality-sensitive
- Task requires multi-hop reasoning or >3 tool calls in a chain
- Input context >100K tokens
- Previous attempt at lower tier produced poor results
Bump down one tier if ALL of:
- Output is intermediate (not user-facing)
- Task is deterministic and templated
- Correctness is cheaply verifiable
Step 3 — Fallback / escalation
- Malformed output — retry once at same tier, then escalate
- Logically inconsistent — escalate one tier
- Confident and well-formed — done
Token Efficiency Rules
- Trim system prompts — under 500 tokens unless required.
- Batch — one call with 10 items beats 10 sequential calls.
- Cap
max_tokens — set to minimum plausible output length.
- Cache-friendly prompts — stable content at the top.
- Avoid redundant context — summarize prior turns, don't echo.
- Structured output — JSON/tables over prose when consumer is a machine.
- Minimize calls per interaction — batch user inputs before calling API.
Multi-Call Pipeline Design
[Router / Planner] → Tier 1 or 2 (classify intent, decompose task)
[Subtask Workers] → Tier 1 (extraction, formatting, simple transforms)
[Synthesizer] → Tier 2 (combine, reason across results)
[Quality Gate] → Tier 1 (schema check) → escalate to Tier 2 if fail
[Final Response] → Tier matching user-facing quality bar
General rule: cheap models do the volume work; expensive models do the judgment.
Project-Specific Routing
(LangGraph tax pipeline)
- Intent classification: Haiku | RAG scoring: Haiku | Tax reasoning: Sonnet/Opus
- Response synthesis: Sonnet minimum | Security guardrails: Haiku
(guest messaging pipeline)
- Webhook parsing: Haiku | Guest messages: Sonnet | Review responses: Sonnet
(interview pipeline)
- Form extraction: Haiku | State transitions: Haiku | Tax calculation: Sonnet
/ Infrastructure
- No API calls — token-miser applies only to subagent routing during Claude Code sessions
Quick Reference Card
SUBAGENT ROUTING (Claude Code):
Explore/search/grep: haiku Research/synthesis: sonnet
Code gen (simple): sonnet Code gen (complex): opus
Test/build/git: haiku Planning/arch: opus
Docs/formatting: haiku Debugging: sonnet
API / ARTIFACT ROUTING:
Task complexity: LOW → Haiku MED → Sonnet HIGH → Opus
Context size: <20K → Haiku 20K-100K → Sonnet >100K → Sonnet/Opus
User-facing: No → Haiku Yes → +1 tier if quality-sensitive
Cost ratio: 1x ~3x ~5x
NOTE: Opus 4.6 at $5/$25 is only 5x Haiku (not 15x like legacy Opus 4.1).
When in doubt between Sonnet and Opus, quality wins.
1---2name: token-miser3description: Minimize Claude token and cost waste across ALL surfaces — Claude Code subagents, API calls in code, and artifacts. Routes subagent model selection via the Agent tool's model parameter. Recommends /model switches when the current model is overkill or underpowered. Applies to any code importing anthropic or calling /v1/messages. Trigger on: "API call", "artifact", "pipeline", "multi-agent", "LangGraph", "which model", "save tokens", "reduce cost", "claude API", "token usage", "context window", any code importing anthropic or calling /v1/messages, subagent launches, or any discussion about optimizing Claude usage or costs.4---56# Token-Miser78Route every Claude interaction to the cheapest model that can handle it reliably.9This applies to **three surfaces**:10111. **Claude Code subagents** — set `model` param on every `Agent` tool call122. **API calls in code** — model selection when writing code that calls Anthropic133. **Artifacts** — model selection for API calls inside artifacts1415Never mention routing decisions to the user unless asked — just apply them.1617---1819## Scope2021| Surface | Mechanism | What Token-Miser Does |22|---------|-----------|----------------------|23| **Claude Code subagents** | `Agent` tool `model` param (`haiku`, `sonnet`, `opus`) | Route every subagent to cheapest viable model |24| **Claude Code main model** | Recommend `/model` switch to user | Flag when current model is overkill or underpowered |25| **API calls in code** | Model string in `anthropic.messages.create()` | Route to optimal model, escalation wrappers, batching, caching |26| **Artifacts** | Model string in browser API calls | Same as API calls |2728---2930## Model Tiers (Verified 2026-03-17)3132| Tier | Model | Agent Param | API String | Cost | Context |33|------|-------|-------------|-----------|------|---------|34| 1 — Fast/Cheap | Haiku 4.5 | `haiku` | `claude-haiku-4-5-20251001` | ~1x | 200K |35| 2 — Balanced | Sonnet 4.6 | `sonnet` | `claude-sonnet-4-6` | ~3x | 200K |36| 3 — Powerful | Opus 4.6 | `opus` | `claude-opus-4-6` | ~5x | 200K (1M beta) |3738See `references/model-pricing.md` for detailed token pricing.3940---4142## Claude Code Subagent Routing4344**This is the primary cost lever.** Every `Agent` tool call accepts an optional45`model` parameter. Always set it explicitly based on the task.4647### Subagent Routing Table4849| Subagent Task | Model | Rationale |50|--------------|-------|-----------|51| File search, pattern matching (Explore) | `haiku` | Read-only, deterministic |52| Simple grep/glob delegation | `haiku` | Mechanical search |53| Code review (style, linting) | `haiku` | Pattern matching, checklist |54| Test runner, build validation | `haiku` | Execute + report, no reasoning |55| Research — single focused question | `sonnet` | Needs synthesis |56| Research — broad exploration | `sonnet` | Multi-step, judgment calls |57| Code generation (simple function, boilerplate) | `sonnet` | Needs correctness |58| Code generation (complex, multi-file, architectural) | `opus` | High stakes, needs reasoning |59| Planning / architecture design | `opus` | Open-ended, judgment-heavy |60| Debugging (root cause analysis) | `sonnet` | Start here, escalate if stuck |61| Writing documentation | `haiku` | Templated, low ambiguity |62| Git operations, status checks | `haiku` | Mechanical |6364### When NOT to downgrade subagents6566- Subagent will **write code** that gets committed — sonnet minimum67- Subagent needs to **make judgment calls** about ambiguous requirements — sonnet+68- Subagent result feeds directly into **user-facing output** — match main model tier69- Task previously failed at a lower tier — escalate, don't retry same tier7071---7273## Main Model Recommendations7475| Situation | Recommendation |76|-----------|---------------|77| User on Opus, doing simple file edits / git ops | Suggest: `/model sonnet` would save cost |78| User on Haiku, attempting complex multi-file refactor | Suggest: `/model opus` recommended |79| User on Sonnet, task is clearly Haiku-tier | Don't mention — switching friction not worth it |80| User on Sonnet, task is clearly Opus-tier | Suggest only if quality likely to suffer |8182**Rule:** Only recommend switches when the cost/quality delta is significant.83Sonnet is always an acceptable default.8485---8687## Freshness Protocol88891. **Read** `references/model-pricing.md` header date.902. **If <90 days old** — use as-is.913. **If >90 days old** — web-search `Anthropic Claude API pricing` before using prices.924. **If prices changed** — update the reference file.9394Skip when: applying routing table (no dollar amounts needed), subagent model95selection (relative tiers don't change with pricing), token efficiency rules.9697---9899## Routing Decision Framework100101### Step 1 — Classify the task102103| Task Type | Default Tier | Notes |104|-----------|-------------|-------|105| Simple Q&A, classification, extraction | 1 | Single-turn, clear answer |106| Summarization (short doc, <20K tokens) | 1 | |107| Summarization (long doc, >20K tokens) | 2 | Context pressure |108| Code generation (boilerplate, simple functions) | 1 | |109| Code generation (complex logic, multi-file) | 2 | |110| Code debugging / root cause analysis | 2 | Start here |111| Reasoning / multi-step math / analysis | 2 | Start here |112| Complex reasoning with ambiguous constraints | 3 | |113| Long-context document processing (>100K tokens) | 2 | Watch cost |114| Tool use — simple, single tool | 1 | |115| Tool use — multi-tool, agentic chains | 2 | |116| Tool use — autonomous, open-ended agent | 3 | |117| Structured output / JSON extraction | 1 | |118| Grading / judging other model outputs | 2 | Avoid circular bias |119120### Step 2 — Apply modifiers121122Bump **up** one tier if:123- Output is user-facing AND quality-sensitive124- Task requires multi-hop reasoning or >3 tool calls in a chain125- Input context >100K tokens126- Previous attempt at lower tier produced poor results127128Bump **down** one tier if ALL of:129- Output is intermediate (not user-facing)130- Task is deterministic and templated131- Correctness is cheaply verifiable132133### Step 3 — Fallback / escalation134135- Malformed output — retry once at same tier, then escalate136- Logically inconsistent — escalate one tier137- Confident and well-formed — done138139---140141## Token Efficiency Rules1421431. **Trim system prompts** — under 500 tokens unless required.1442. **Batch** — one call with 10 items beats 10 sequential calls.1453. **Cap `max_tokens`** — set to minimum plausible output length.1464. **Cache-friendly prompts** — stable content at the top.1475. **Avoid redundant context** — summarize prior turns, don't echo.1486. **Structured output** — JSON/tables over prose when consumer is a machine.1497. **Minimize calls per interaction** — batch user inputs before calling API.150151---152153## Multi-Call Pipeline Design154155```156[Router / Planner] → Tier 1 or 2 (classify intent, decompose task)157[Subtask Workers] → Tier 1 (extraction, formatting, simple transforms)158[Synthesizer] → Tier 2 (combine, reason across results)159[Quality Gate] → Tier 1 (schema check) → escalate to Tier 2 if fail160[Final Response] → Tier matching user-facing quality bar161```162163**General rule:** cheap models do the volume work; expensive models do the judgment.164165---166167## Project-Specific Routing168169### <your-project> (LangGraph tax pipeline)170- Intent classification: Haiku | RAG scoring: Haiku | Tax reasoning: Sonnet/Opus171- Response synthesis: Sonnet minimum | Security guardrails: Haiku172173### <internal-project-3> (guest messaging pipeline)174- Webhook parsing: Haiku | Guest messages: Sonnet | Review responses: Sonnet175176### <internal-project-4> (interview pipeline)177- Form extraction: Haiku | State transitions: Haiku | Tax calculation: Sonnet178179### <internal-project-1> / Infrastructure180- No API calls — token-miser applies only to subagent routing during Claude Code sessions181182---183184## Quick Reference Card185186```187SUBAGENT ROUTING (Claude Code):188 Explore/search/grep: haiku Research/synthesis: sonnet189 Code gen (simple): sonnet Code gen (complex): opus190 Test/build/git: haiku Planning/arch: opus191 Docs/formatting: haiku Debugging: sonnet192193API / ARTIFACT ROUTING:194 Task complexity: LOW → Haiku MED → Sonnet HIGH → Opus195 Context size: <20K → Haiku 20K-100K → Sonnet >100K → Sonnet/Opus196 User-facing: No → Haiku Yes → +1 tier if quality-sensitive197 Cost ratio: 1x ~3x ~5x198199NOTE: Opus 4.6 at $5/$25 is only 5x Haiku (not 15x like legacy Opus 4.1).200When in doubt between Sonnet and Opus, quality wins.201```
scoobydont-666