Token economics: what Claude Code actually costs

TLDR; Most Claude Code spend goes to context, not prompts or output: files read, conversation history, and system prompts reloaded every session. Sonnet-default routing on API billing cut my monthly spend by roughly 35%. On a flat plan, keep Opus in the main session, change effort instead of model, and send search to Haiku. Clear stale sessions and keep CLAUDE.md lean.

My first month running Claude Code across client projects, the API bill was over $900. I wasn’t doing anything unusual: Rails features, debugging, code reviews, content generation across six concurrent engagements. I hadn’t thought about where the tokens were going. It felt like a utility you don’t monitor until the invoice arrives.

The second month was $340. Same workload. Same clients. Same output quality. The difference was understanding what drives cost. Most tokens go to context: files Claude reads, conversation history that accumulates, system prompts that load silently every session. Vendor figures point the same way: in spring 2026 Morphllm cited one developer’s count of 42 agent runs that found 70% of tokens were waste, and another analysis that put 87% of tokens on finding code rather than writing it.

The pricing structure

Claude Code API usage bills by token consumption. Subscription plans provide limited usage allowances instead, with limits affected by model choice, effort, context size, and concurrent work. How you access Claude Code changes both the invoice and the capacity constraint.

API pricing (pay-as-you-go)

This is the transparent option. You see every token, and you pay market rate:

Scroll sideways →

Fable 5.1 is a different kind of entry from the rest. Anthropic positions it for the most demanding long-horizon reasoning, and it costs 2.5x Opus 5.5. Opus 5.5 now beats it on Terminal-Bench 4.0, so treat Fable as a deliberate escalation for one hard problem. Everything below assumes an Opus-and-down lineup.

Output tokens cost 5x input tokens across all models. Extended thinking and verbose code generation burn output tokens, which is where costs escalate fast.

Cache reads are discounted heavily. When Claude re-reads your system prompt, CLAUDE.md, or recently accessed files, those tokens hit the cache at 90% off the standard input price, 95% off on Opus 5.5 and Sonnet 5.5, and 97.5% off on Fable 5.1. In heavy sessions, cache reads make up the bulk of your input cost. This is why prompt caching cuts input cost so sharply; the content Claude loads repeatedly barely costs anything after the first read.

Subscription plans

For most individual developers, a subscription is cheaper than API:

The economics are stark for heavy users. By Verdent’s own figures, one developer tracked 10 billion tokens over eight months, and the API equivalent exceeded $15,000. Max subscription for the same period: $800. A saving of roughly 95%.

I ran API billing for a long time because I wanted the granular tracking and model-routing control, and I’ve since moved to Max 20x (more on what that changes below). I would not point someone starting today down that same path, though. API pay-as-you-go is uncapped, and for heavy Claude Code use it is the most expensive way to buy tokens, as the $15,000 figure above shows. You also no longer need to be on API to see where your tokens go: ccusage reads Claude Code’s local session files and reports the same consumption on any plan.

The lower-risk path today is to start on Pro at $20/month, which includes Claude Code, and enable usage credits so that passing your plan cap bills the overflow at API rates instead of cutting you off mid-session. Track your real usage with ccusage for a few weeks, then move up a tier on one of two triggers: you are regularly hitting the cap and it interrupts your work, or your monthly overage is approaching what the next tier up would cost anyway. Because usage credits bill at full API rates, that second crossover arrives quickly, and when it does the flat plan wins outright. Let the overage bill decide the timing.

What “average” looks like

Across enterprise deployments, Anthropic reports an average of $13 per developer per active day, with $150-250 per developer per month typical and 90% of users staying under $30 per day. Those numbers feel right for steady, deliberate use. The outliers, and I’ve been one, come from running multi-agent workflows without model routing discipline.

Model routing

The price gap between models is wide: for prompts up to 100,000 tokens Haiku 5.5 costs a fortieth of Opus 5.5 on input and output, and Sonnet 5.5 costs half. Running everything on Opus because it’s “the best model” is like driving a truck to the corner shop. Running everything on Haiku hands judgement to a model that hallucinates more than other recent Claude models, according to its system card.

The roughly 35% saving came from the routing I ran on API billing: Sonnet by default, Opus for architecture and review, Haiku for exploration. On API or Pro billing that is still the safer baseline. Since moving to Max 20x I run Opus 5.5 at medium in the main session and route subagents by job, as listed under the subagent cost multiplier. The model selection guide has the full table, with the effort level for each kind of work and the eval results behind each row.

On Max the per-token gap between models does not appear as a line item. It shows up as allowance used, and heavier models, large contexts and parallel subagents all spend it faster. The gap still shows in Claude Code’s cost reporting: in the month to 8 October, Explore subagents cost me $33.69 at list price, $31.88 of it on Opus, until a hook routed them to Haiku.

Each model has its own cache, so switching models mid-session makes the next request read the whole conversation uncached. Changing effort keeps the cache on the 5.5 models and Fable 5.1. Pick the main-session model at the start and change effort instead.

Effort

Effort sets how many tokens Claude spends on a response, and its levels run low, medium, high, xhigh, max. It shapes thinking and every other output token, tool calls included. At lower effort Claude makes fewer tool calls, batches operations together, and skips the preamble before acting. On agentic work, where tool calls are most of the spend, that matters more than the thinking budget does.

As of October 2026, Claude Code defaults to medium on Opus 5.5, Sonnet 5.5 and Haiku 5.5, and to high on most older models; Opus 4.7 defaults to xhigh (model configuration docs). A subagent without its own effort setting runs at the session’s level, so a file-locating agent spawned from a high session runs at high. In my tracking that is the commonest overspend, and no invoice line shows it. Pin effort in the agent definition for anything you delegate often, or pass a per-spawn effort (Claude Code v2.1.292 and later, per the subagents docs).

When output is disappointing, raise the model before you raise the budget. In Anthropic’s advisor pattern benchmarks, Haiku 4.5 with an Opus 4.6 advisor scored 41.2% on BrowseComp against 19.7% for Haiku alone. A stronger model in the loop more than doubled the score. More token budget on a model that’s out of its depth mostly buys a longer wrong answer.

That result came from Haiku 4.5. Haiku 5.5 and Sonnet 5.5 executors never called an Opus advisor across 198 questions when nothing in the prompt asked them to, according to Anthropic’s cost and intelligence guide. Measure how often your executor calls the advisor; if it stays near zero, upgrade the executor instead.

Effort guidance expires

Every effort setting in this guide, and in the model selection table, is a snapshot. What a given effort level buys you shifts with each model release, sometimes in the opposite direction from the last one, and the vendor guidance moves with it.

The clearest illustration is one generation of Opus to the next. For Opus 4.7 and 4.8, Anthropic’s advice was to start at xhigh for coding and agentic work and treat high as the floor for anything intelligence-sensitive. For Opus 5, the same page says start at high, the default, and use low and medium liberally as your primary cost control wherever your evals show quality holds. Same vendor, same task, one release apart, opposite recommendations. Opus 5.5 moved the default down again, to medium. The docs are explicit about the implication: if you carried effort settings over from an earlier model, run a fresh sweep rather than reusing them.

Capability has moved to cheaper models before. Anthropic’s own comparison has Opus 5 at maximum effort landing within 0.5% of Fable 5’s peak CursorBench score at half the cost per task. It also beats Fable’s best OSWorld result at just over a third of the cost, though Fable sits a full tier above it. That parity holds only at maximum effort. Model and effort closed the gap together, so treat them as one setting. Anthropic still calls Fable 5.1 its most capable widely released model and points workloads that need the highest available capability at it.

The practical habit: when a new model lands, re-run your own cheapest and most expensive delegated tasks across two or three effort levels before you update any agent definitions. It’s a twenty-minute check. The failure mode it prevents is a fleet of agents pinned at settings that were correct for a model you no longer run. They overpay on the mechanical work and under-think the hard work, and nothing in the bill tells you which.

Context window economics

Every message you send carries the weight of everything before it. The startup load takes your actual working space on a 200K window down to roughly 145,000-167,000 tokens before you’ve typed a word. It covers the system prompt, CLAUDE.md files, MCP tool names and the compaction buffer; full tool schemas defer-load on current clients, so MCP costs far less than it used to. Run /context in a fresh session for your own breakdown rather than trusting a published figure; the reserve moves with the model, the window and the release.

That’s the starting budget. Every file read, every tool output, every exchange; it accumulates. A typical file read costs 500-2,000 tokens. A test suite output can run 5,000+. Ten rounds of conversation with code generation burn through context fast.

Every current model runs with a 1M-token window by default in Claude Code (model configuration docs), and Opus and Sonnet charge the same per-token rate across it. The figures above assume a 200K window. I measured the thresholds below there and haven’t re-measured them at 1M. A bigger window still bills every token you park in it.

Quality degrades as the context fills, which costs more than the token bill shows. Research on long-context language models documents a U-shaped performance curve; models prioritise information at the beginning and end of the context window and deprioritise the middle. Your architectural decisions from thirty minutes ago drift into that zone. Claude still has technical access but functionally weighs them less.

The degradation phases below are working thresholds from my own tracking:

1. Fresh (0-40% utilisation): sharp, follows all instructions, remembers everything
2. Working (40-65%): still effective, start planning your next compact or clear
3. Degrading (65%+): missed instructions, repeated suggestions, reversed earlier decisions

Scroll sideways →

Auto-compaction keeps a reserved buffer, but its effective trigger can change with the model, context window, and release. I set CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=65 on the configurations where I have verified the override, but the better habit is proactive management.

The clear discipline

/clear is free. Zero tokens. It wipes conversation history and gives you a clean window. The re-establishment cost, Claude reloading CLAUDE.md, reading a few key files, runs 3,000-5,000 tokens. That’s trivial compared to fighting a degraded 150K-token session.

My rule: if the next task doesn’t need the context from the current task, clear. Finish a feature, commit, /clear, start the bug fix. Treating sessions as disposable rather than precious is the simplest cost reduction available. See the session craft guide for the full lifecycle model.

Compact with guidance

When you’re mid-task and can’t start fresh, /compact summarises the conversation to free context. The token reduction varies by model, configuration, and release. Compaction without guidance is indiscriminate: an architecture decision from forty minutes ago might get reduced or dropped.

Guided compaction changes the outcome:

/compact Preserve: the API endpoint naming convention, 
the pagination approach (cursor-based), and the three 
test failures we haven't addressed yet.

Now Claude knows what to keep. Implementation details of committed files can safely compress. Open decisions stay intact.

The subagent cost multiplier

Running parallel agents is faster. It’s also more expensive per token than you’d expect, because each agent loads its own context independently.

A typical subagent session on my Rails projects:

Run five agents and each carries that overhead; they share no context pool. Anthropic’s cost documentation now frames team consumption as a function of active teammates, their models, and how long they run. Ordinary subagents are usually cheaper than a peer team, but the shape of the cost is the same: every agent pays its own entry price.

Model selection is the mitigation:

• Explore agents (read-only search): Haiku. Built-in Explore uses the main conversation’s model unless you name one, so an Opus session makes every Explore run an Opus run.
• Plan agents (architecture): Opus. Design decisions benefit from the strongest model.
• Implementation agents (routine code): Sonnet. Standard Rails models and tests don’t need Opus.
• Review agents (catching bugs): Opus. Subtle issues require deep reasoning.

In the onboarding feature case study from the multi-agent guide, mixing models across six agents kept the blended cost at roughly a third of what all-Opus would have been, and it compressed 60+ minutes of sequential work into 20 minutes of wall-clock time.

My working break-even is a task that would take more than 45 minutes sequentially and has at least three separable concerns. That threshold comes from my own projects and billing assumptions. Below it, I usually find a single well-managed session cheaper.

The CLAUDE.md token audit

Your CLAUDE.md loads at the start of ordinary sessions and in custom subagent contexts that inherit project instructions. Built-in Explore and Plan agents use narrower context. Whatever loads is recurring context even when most lines are irrelevant to the current task.

I ran this experiment on a client project. The CLAUDE.md had grown organically over months: coding conventions, deployment procedures, domain knowledge, common gotchas, example patterns. Thorough, but also 280 lines and roughly 8,500 tokens.

The audit went through four steps. First, measure: run /context at the start of a fresh session. My CLAUDE.md was consuming 4.3% of the 200K context window before I’d done anything. Across a day of 15 sessions, that’s 127,500 input tokens in CLAUDE.md loading alone before cache discounts: roughly $0.51 on Opus 5.5, or $0.26 at Sonnet’s standard $2/MTok rate. Actual billed input can be lower when prompt caching applies.

Second, categorise every line. I tagged each instruction as essential (behaviour-changing rules Claude needs every session, naming conventions, forbidden patterns, test commands), situational (domain knowledge needed only for specific tasks, deployment steps, API quirks, client-specific context), or discoverable (information Claude could find by reading the codebase, file structure, existing patterns, module purposes).

Third, move situational knowledge to skills. Deployment procedures became a /deploy-checklist skill. Client-specific domain rules became per-client skills loaded only when working on that client. API integration patterns became a skill invoked when touching those endpoints. Skill descriptions still occupy some startup context, but the full instructions and references load only when needed.

Fourth, delete discoverable content. Claude can read config/routes.rb when it needs the routing structure. It can check the test suite to understand the test patterns. Documenting these in CLAUDE.md is paying to tell Claude what it can see for itself.

Result: 280 lines down to 85 lines. 8,500 tokens down to roughly 2,400. Same output quality; I ran the same set of tasks before and after and compared the results. The trimmed version produced slightly better output on one task, possibly because less irrelevant context meant more attention on the instructions that mattered.

The target from Anthropic’s memory documentation is roughly 200 lines or fewer, essentials only. The figure is guidance. I’d push further, to under 100 lines if you’re disciplined about moving specialised knowledge into skills.

What cuts cost most

These are ranked by impact from my tracking. The first three account for most of the savings.

• Route models deliberately. Sonnet-default routing on API billing cut my spend by roughly 35%. On a flat plan, keep one model in the main session and change effort; on any plan, send search and extraction to Haiku and keep judgement on Opus.
• Clear between unrelated tasks. Don’t carry stale context. The few minutes of re-establishment save twenty minutes of fighting a degraded session, and the tokens that fighting burns.
• Keep CLAUDE.md lean, move specialised knowledge to skills. It is recurring context in ordinary sessions and custom agents that inherit it; built-in Explore and Plan agents use narrower context. Under 100 lines is achievable in my projects.
• When you compact, tell Claude what to preserve. Unguided compaction drops the decisions that shape everything downstream; the architecture choices from earlier in the session are what you need in the next.
• For orientation work, spin up a Haiku Explore agent rather than reading twenty files in your main session. It reads the files in its own context and returns a 1,000-token summary. Loading all those file contents into your primary window costs more and stays there.
• Use Plan Mode (Shift+Tab) for anything non-trivial. A well-planned task often completes in a single pass. An unplanned task generates multiple rounds of course corrections, each burning context.
• Prefer a CLI over an MCP server when one exists. Tool schemas and verbose JSON responses are context you pay for on every call. I’ve replaced several MCP servers with thin CLI wrappers for Search Console, analytics, and SEO data. In my measurements, default filtering and compressed output alone saved over 80% on data-heavy queries. Anthropic’s cost documentation makes the same recommendation: CLI tools like gh and aws add no tool definitions to every request.
• Rewrite routine dev commands to token-lean equivalents. A hook-based proxy that does this saves me 60-90% on everyday git and test operations.
• Filter data before Claude sees it. A 10,000-line log file through grep -E "(ERROR|WARN)" becomes a few hundred lines. A hook on your test runner that strips passing tests and shows only failures can cut test output from 5,000+ tokens to a few hundred. The skills and hooks guide covers the implementation.
• Write specific prompts. “Add input validation to the login function in auth.ts” costs far less than “improve the auth module.” Vague requests trigger broad scanning; Claude reads files looking for what you might mean. Specificity lets Claude work with minimal file reads.
• Cap extended thinking. Thinking tokens bill as output tokens at 5x the input rate. For standard implementation work, deep reasoning isn’t needed. Use /effort (levels run low through max) to turn thinking down for straightforward tasks and up for the hard ones. This is now the canonical lever; current adaptive-reasoning models ignore the older MAX_THINKING_TOKENS flag.
• Track your spend. Install ccusage and run ccusage daily --breakdown. Claude Code’s current /usage view shows session and plan consumption; API users can also inspect billed cost. Usually one or two patterns account for most of the waste. Fix those first; the remaining patterns cost far less.

Before an Applied AI build ships, I set cost as one of its measures, with time saved and quality.

---

Related reading

• Model selection, which Claude for which job, the model and effort for each kind of work, with the evidence behind each choice
• Session craft, when to start fresh, resume, or compact, the full session lifecycle model for context management
• Multi-agent orchestration, running parallel agents on real projects, parallel execution with cost data and model mixing
• Skills, hooks, agents, and commands, the definitive guide, moving knowledge from CLAUDE.md to on-demand skills
• Top 10 ways to optimise Claude Code token usage, the quick-reference version
• Stop letting your AI agent do a script’s job, moving deterministic steps out of the agent loop

Sources

• Manage costs effectively, Claude Code Docs, Official Anthropic guidance on cost tracking, team limits, and reduction strategies. Documentation
• The Real Cost of AI Coding in 2026, Morphllm, archived May 2026. Cites a DEV Community developer’s 42 agent runs (70% of tokens wasted) and a separate analysis (87% of tokens spent finding code). The live page has since dropped both figures. Vendor analysis, secondary
• Claude Code Pricing 2026: Plans, Token Costs, and Real Usage Estimates, Plan comparison with the 10-billion-token case study. Guide
• Lost in the Middle: How Language Models Use Long Contexts, Liu et al., 2023. The research behind context window degradation patterns. Academic paper
• ccusage, Claude Code Usage Analysis, CLI tool for tracking Claude Code token consumption from local JSONL files. Open-source tool
• Use Claude Code with your Pro or Max plan, Anthropic. Confirms Claude Code access on Pro and the ability to enable usage credits that bill overflow at API rates past the plan cap. Documentation
• Anthropic API Pricing, Current per-token pricing for all Claude models. Includes the Haiku 5.5 price tier above 100,000 tokens and the cache-read multipliers. Documentation
• The advisor strategy, Anthropic, Haiku 4.5 with an Opus 4.6 advisor against Haiku alone on BrowseComp. Product announcement
• Effort, Anthropic, Per-model effort guidance, model support, and the effect on tool calls. Source for the shift in recommended starting effort between Opus 4.8 and Opus 5. Documentation
• Prompt caching, Claude Code Docs, Each model has its own cache; which settings keep it across an effort change. Documentation
• Model configuration, Claude Code Docs, Claude Code effort defaults and the 1M-token default window. Documentation
• Optimizing for cost and intelligence, Anthropic, Advisor consult rates for the 5.5 models. Documentation
• Create custom subagents, Claude Code Docs, Subagent model and effort settings, per-spawn effort, and the built-in Explore agent’s model. Documentation
• Claude Haiku 5.5 system card, Hallucination results against other Claude models. System card
• Introducing Claude Opus 5.5, Anthropic, Terminal-Bench 4.0 against Fable 5.1. Product announcement
• Introducing Claude Opus 5, Anthropic, Source for the CursorBench and OSWorld comparisons against Claude Fable 5 at a fraction of the cost per task. Product announcement

Common questions

Is the $20 Claude plan worth it?

The Pro plan at $20/month suits light use, a few sessions daily. If you’re using Claude Code more heavily, Max 5x at $100/month is likely the better deal. Verdent reports one developer who tracked eight months of usage: the API equivalent exceeded $15,000 against $800 on Max 5x.

Why is Claude Code expensive?

Most of the cost comes from context, not the prompts you type or the code Claude generates: files Claude reads, conversation history that accumulates, and system prompts that reload every session. My own first month running it across client projects hit over $900 before I understood where the tokens were going; the second month, same workload, was $340 once I addressed that.

Is Claude Code free?

No, it runs on either pay-as-you-go API pricing or a subscription plan starting at $20/month for Pro, with Max plans at $100 or $200/month for heavier use. For regular use a subscription usually works out cheaper; move up a tier once your plan plus overage approaches the next tier’s price.

Is it worth paying for Claude for coding?

For heavy, regular use the numbers support it: Anthropic’s own data puts typical enterprise spend at $150-250 per developer per month, and 90% of users stay under $30 a day. I ran API billing for the granular tracking but have since moved to a Max 20x subscription myself, which changes the routing calculus but not the underlying value.