Claude Code Pricing: Optimize Your Token Usage & Costs

Problem: Claude Code costs are climbing, you are hitting usage limits mid-task, or you are not sure which subscription tier matches your workflow.

Most Claude Code token optimization advice stops at "switch to Sonnet and clear your context more often." That advice is correct and it is worth roughly what it costs to follow. The larger savings are structural: they come from how you split a task across models, and from whether the cheaper model you delegated to is reading from cache or paying full price for the same context on every call.

Anthropic has published numbers for that split. On BrowseComp, a Claude Fable 5 orchestrator delegating to Claude Sonnet 5 worker sub-agents reached 96% of Fable 5's performance at 46% of the price. This guide covers the plan math, then that delegation economics, then the cache rule that decides whether the savings survive contact with a real session.

Quick Win: look at your actual consumption before changing anything.

/usage      # plan limits, and what's eating them
/context    # what's currently loaded in this session

On a Pro, Max, Team, or Enterprise plan, /usage attributes recent consumption to skills, subagents, plugins, and individual MCP servers, each as a percentage of the total. It flags behaviors that account for 10% or more of recent usage, including long context and cache misses. Press d or w to toggle between the last 24 hours and the last 7 days. Optimizing before you have this breakdown is guesswork.

Understanding Claude Code Pricing

Claude Code needs at least a Pro subscription ($20/month), since the free tier has no terminal access. Above that, the tiers differ in how much you can draw per five-hour window and per week.

Anthropic doubled the five-hour rate limits and removed the peak-hour reduction on 2026-05-06, which changed the per-window ceilings substantially. The weekly cap moved separately. Rather than repeat figures that shift, see what actually doubled and what did not for the current windows.

API pay-per-use is the other path, and its list prices are the anchor for every delegation decision below:

Sonnet 5 is on introductory pricing of $2/$10 through August 31, 2026, after which it moves to $3/$15. Two things fall out of this table immediately. Opus 5 is 2.5x Sonnet 5 on input during the introductory window, and 1.67x once Sonnet 5 returns to $3/$15, not the 5x that older guides still quote. That 5x came from Opus 4.1 at $15/$75 against Sonnet at $3/$15, and Opus 4.1 is now deprecated with a retirement date of August 5, 2026. Any advice built on it is pricing a model that is about to be switched off. And a cache read costs 10% of the standard input price on every model, which is the single largest lever in this guide.

Track Spend Over Time

/usage answers "what is happening right now." For trends across days and weeks, add a second tool.

For API and cloud-provider usage, ccusage reads your local session history and breaks down cost by day and by model:

npm install -g ccusage
 
ccusage daily              # daily breakdown
ccusage monthly            # monthly aggregation
ccusage blocks --live      # live five-hour billing window
ccusage daily --breakdown  # per-model split

Note the package name. Older guides, including an earlier version of this page, tell you to install @ryoppippi/ccusage, which now 404s on the registry. The published package is plain ccusage.

Filter by date range when you are chasing a spike:

ccusage daily --since 20260701 --until 20260731

Two caveats on any local tool. It prices tokens at standard list rates, so it will not reflect promotional pricing or contracted discounts, and it only sees this machine. For authoritative numbers use the Claude Console usage page, or, on Team and Enterprise plans, the spend report in your org analytics.

Delegate Expensive Thinking to Cheap Execution

Here is the part almost nobody writes about. Choosing one model for a whole task is a false constraint. You can run two, and the arithmetic is better than most developers expect.

Two shapes are documented, and they differ in which model holds the steering wheel.

The Fable orchestrator: strong planner, cheap workers

A Fable 5 orchestrator decomposes the task, then hands concrete units of work to Sonnet 5 sub-agents. The workers absorb the bulk of the reading and writing, so the bulk of the tokens bill at the worker rate. The orchestrator only sees plans and summaries.

On BrowseComp, that configuration scored 86.8% accuracy at $18.53 per problem against Fable 5 alone at 90.8% and $40.56, which is 96% of the performance for 46% of the price. You give up four points of accuracy and keep more than half your budget.

To avoid a collision with terms already used elsewhere on this blog: this is model-tier orchestration, about which model runs which step. It is a different axis from the coordinator-and-specialists structure covered in agent design patterns, which is about roles rather than price tiers. The two compose. You can run a specialist-shaped team where every specialist is a Sonnet worker.

The Fable advisor: cheap executor, occasional escalation

Invert it. A Sonnet 5 executor runs the task start to finish and calls a Fable 5 advisor when it needs steering. The advisor reads the transcript, returns a plan or a course correction, and the executor continues. On SWE-bench Pro, Sonnet 5 with a Fable 5 advisor reached roughly 92% of Fable 5's score at roughly 63% of the price, with the advisor called about once per task.

Anthropic's advisor tool documentation is blunt about why this works: advisor output typically runs 400 to 700 text tokens, so the savings come from the advisor never generating your final output. The executor does that at its lower rate. The docs also note that pairing a Sonnet executor at medium effort with an Opus advisor reaches intelligence comparable to Sonnet at default effort, at lower cost.

One naming warning. "Advisor" here means a same-provider, cost-motivated escalation from a cheaper Claude model to a stronger one. It is not the same as the cross-provider auditor in our model stacking guide, where a rival vendor's model reviews Claude's work specifically because it does not share Claude's assumptions.

Which shape fits your work

In Claude Code, the orchestrator shape is what CLAUDE_CODE_SUBAGENT_MODEL exists for. Set it and every sub-agent runs on the model you name, regardless of what the main session is using:

export CLAUDE_CODE_SUBAGENT_MODEL=claude-sonnet-5

Per sub-agent, the model field in frontmatter accepts the sonnet, opus, haiku, and fable aliases, a full model ID, or inherit. The sub-agent best practices guide covers the routing rules in detail.

Prompt-Cache Discipline: The Rule That Decides Everything

This is where most delegation savings quietly die, and it has nothing to do with which models you picked.

Cache reads cost 0.1x the base input price. A five-minute cache write costs 1.25x, and a one-hour write costs 2x. So a cached context pays for itself after a single read on the five-minute duration, and after two reads on the one-hour duration. Everything after that is close to free.

The failure mode: you spawn a fresh worker for every request. Each new worker starts with a cold cache, so it pays the full write price for context it has never seen. Do that ten times and you have paid the context write ten times, at 1.25x input each, instead of once plus nine reads at 0.1x. The delegation saved you nothing, because you replaced a discount you were already getting with a repeated setup charge.

The fix is one sentence. Route repeat calls to the same worker so its cache accumulates. Give a persistent sub-agent follow-up messages rather than spawning a new one per request. The prefix stays stable across calls, so each call reads up to the previous point and pays only for the delta. Anthropic's advisor documentation makes the same tradeoff explicit for advisors: the cache write costs more than the reads save at two or fewer calls per conversation, breaks even around three, and improves from there.

Two Claude Code specifics matter here:

• Cache lifetime is longer on a subscription. It is one hour on a subscription plan, and drops to five minutes once you are drawing on usage credits. On an API key or a cloud provider it is five minutes by default. A twenty-minute coffee break costs a subscriber nothing and costs a credit-drawing user a full context reprocess.
• The first message after a long break misses the cache. Claude Code sends your whole conversation with every message, so that first message reprocesses everything. This is why /usage flags cache misses as a distinct cost driver.

Claude Code enables prompt caching by default. The DISABLE_PROMPT_CACHING variable and its per-model siblings exist for benchmarking, not for production. Leave them off.

This is also the reason resumable sub-agents beat one-shot ones on cost as well as on quality. Persistent sub-agents keep their loaded context, so a follow-up round reuses an investment you already paid for.

When Delegation Costs More Than It Saves

Delegation is not free, and treating it as free is how a cost optimization turns into a cost increase.

Every token that crosses a model boundary is billed at least twice. The orchestrator writes a brief and pays for the output; the worker reads that brief and pays for the input. The worker writes a report and pays for it; the orchestrator reads the report and pays again. On top of that, parallel workers do not talk to each other, so two of them researching adjacent questions will partially duplicate each other's reading.

That overhead is roughly fixed per handoff, while the savings scale with how many tokens each worker absorbs. Which means the arithmetic flips on small tasks. Anthropic's own guidance puts a number on the extreme case: agent teams use approximately 7x more tokens than a standard session when teammates run in plan mode, because each teammate maintains its own context window as a separate Claude instance.

The decision rule is a question about task shape, not about model quality. Will each worker absorb enough tokens to outweigh a roughly fixed handoff cost? On a large research sweep, yes, comfortably. On a three-file refactor, no. We cover the failure cases and how to spot them in advance in when multi-agent orchestration costs more than it saves.

Real Optimization Commands

Model switching with /model

/model sonnet   # default for most tasks
/model opus     # complex architecture and multi-step reasoning
/model fable    # the specialist you call when everything else is stuck

Start every session on Sonnet. Escalate deliberately. Note that on a subscription, session and weekly windows are shared across models, so switching with /model does not restore access after "You've hit your weekly limit." It does keep you working after a model-specific message such as "You've hit your Opus limit," because that ceiling is per-model.

Context control

/compact    # summarize and continue
/clear      # start fresh for unrelated work

These are not interchangeable. /compact reads the entire conversation in order to summarize it, so compacting a large context is itself a large request. /clear costs nothing. Use /compact when you need continuity and /clear when you are switching to unrelated work. Use /rename before clearing so you can /resume the session later.

Effort, not just model

Effort controls how much work Claude does: how long it thinks, how many files it reads, how far it pushes before checking in. It is a separate dial from model choice, and on routine work it is the cheaper one to turn down. Lower it with /effort, or on models with a fixed thinking budget set MAX_THINKING_TOKENS=8000. Adaptive-reasoning models ignore nonzero budgets, so use effort levels there. Thinking cannot be disabled on Fable 5. Our effort ladder guide covers where each level earns its cost.

Plan mode before expensive operations

Press Shift+Tab to cycle into plan mode before implementation. Claude explores and proposes an approach for approval, which prevents the far more expensive failure of building the wrong thing first. See the planning modes guide.

Environment Variable Cost Controls

# Suppress non-critical background model calls
export DISABLE_NON_ESSENTIAL_MODEL_CALLS=1
 
# Silence cost warnings once you have a baseline
export DISABLE_COST_WARNINGS=1
 
# Route every sub-agent to a cheaper tier
export CLAUDE_CODE_SUBAGENT_MODEL=claude-sonnet-5

The first disables model calls behind non-critical features like suggestions and tips. The second is only reasonable after you have established a baseline with /usage. The third is the orchestrator shape expressed as one line of config, and it is the highest-leverage variable in this list.

Two more structural levers worth more than any variable. MCP tool definitions are deferred by default, so only tool names enter context until Claude uses a specific tool, but unused servers still cost something: run /mcp and disable what you are not using. And a long CLAUDE.md is loaded at session start whether or not it is relevant, so keep it under roughly 200 lines and move specialized instructions into skills that load on demand. ClaudeFast's Code Kit uses progressive disclosure across its skills for exactly this reason, recovering roughly 15,000 tokens per session against loading everything upfront.

The opusplan Strategy

If you want Opus-level reasoning without paying Opus rates for every line of code, the opusplan model alias is model-tier orchestration built into the CLI:

claude --model opusplan

It uses opus during plan mode, then switches to sonnet for execution. It is the same principle as the Fable orchestrator, one tier down and with the routing decided for you. For anyone not ready to configure sub-agent models by hand, this is the cheapest possible entry point into the pattern.

When Things Go Wrong

Approaching a limit? Drop the model and the context together:

/model sonnet
/compact

Hit a hard limit? The message tells you when the window resets. Run /usage-credits if your plan allows drawing past the allowance. If you are on Max and it was Fable specifically that ran out, see how the Fable 5 allowance works, because Fable is capped at half of your weekly limits independently of everything else.

Next Steps

• Run /usage and note which single behavior accounts for the largest share
• Set CLAUDE_CODE_SUBAGENT_MODEL=claude-sonnet-5 and keep your main session where it is
• Route repeat delegations to one persistent worker instead of spawning fresh ones
• Configure model selection and context management for your workflow

The pattern underneath all of this is the same one Anthropic benchmarked: judgment is worth paying for, volume is not. Put the expensive model where it changes the answer, put everything else a tier down, and make sure the tier below is reading from cache.

For scale, Anthropic reports Claude Code averaging about $13 per developer per active day across enterprise deployments, and under $30 for 90% of users. If you are well above that, /usage will usually name the reason before any of this becomes necessary. The commands here are the cheap fix; the delegation split is the structural one, and it is the half almost nobody has configured. For a framework that ships this coordinator-and-executor split by default, the ClaudeFast Code Kit wires the routing, the sub-agent model tiers, and the skill loading together so you are not assembling it from scratch.