Token Miser

Token-Miser

Route every Claude interaction to the cheapest model that can handle it reliably. This applies to three surfaces:

1. Claude Code subagents — set model param on every Agent tool call
2. API calls in code — model selection when writing code that calls Anthropic
3. 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

1. Read references/model-pricing.md header date.
2. If 90 days old — web-search Anthropic Claude API pricing before using prices.
3. 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) | 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

1. Trim system prompts — under 500 tokens unless required.
2. Batch — one call with 10 items beats 10 sequential calls.
3. Cap max_tokens — set to minimum plausible output length.
4. Cache-friendly prompts — stable content at the top.
5. Avoid redundant context — summarize prior turns, don't echo.
6. Structured output — JSON/tables over prose when consumer is a machine.
7. 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:      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.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: scoobydont-666
• Source: scoobydont-666/shared-claude-skills
• License: MIT

Install and usage instructions live in the source repository linked above.