Claude Code token usage, explained

Why your coding session costs what it does

Every Claude bill — API invoice or subscription limit — comes down to one meter: tokens in, tokens out. The pricing page makes it look simple: so many dollars per million input tokens, so many per million output. What it doesn't tell you is that in an agentic coding session the input side of the meter runs far hotter than intuition suggests, because the entire conversation is re-sent on every single turn. I've sold metered infrastructure for fifteen years, and tokens are the first meter I've seen where most customers genuinely cannot say what's spinning it. This is the meter-reading lesson: what a token is, what counts as input and output in an agentic session, why prompt caching rewrites the arithmetic, and which levers actually move the number.

What a token is, and why code costs more than prose

A token is the unit the model reads and writes — a fragment of text, usually part of a word. Anthropic's own glossary pegs a Claude token at roughly 3.5 English characters, which works out to well over a token per word once spaces and punctuation are counted — a thousand words of prose is comfortably north of 1,300 tokens. Code runs heavier per line: braces, operators, underscores, and indentation split into more tokens per character than English does, and a few-hundred-line source file typically weighs in at several thousand tokens. A 2,000-line file the agent decides to read is a five-figure token purchase before anyone has written a line of new code.

Two things about tokenizers trip people up. First, they're model-specific — as of July 2026, Opus 4.7 and later, Sonnet 5, and Fable 5 use a newer tokenizer that produces roughly 30% more tokens for the same text than earlier Claude models (the exact increase varies by content), which shifts anything you budget in tokens even though per-token prices didn't rise with it. Second, tiktoken — the library every blog post reaches for — is OpenAI's tokenizer and undercounts Claude by roughly 15–20% on ordinary text, more on code. The only trustworthy count is the count_tokens endpoint, covered below.

Everything is input: what the meter actually counts

People assume they pay for the code Claude writes. In an agentic session, that's the small line item. Input tokens — the cheaper rate, but vastly higher volume — include:

• The system prompt. Claude Code's own harness instructions, plus your CLAUDE.md and memory files, loaded at session start and present on every request thereafter.
• Tool definitions. Every tool schema the agent could call. Every MCP server you connect adds to this fixed overhead — though Claude Code now defers full MCP tool definitions by default, so only tool names sit in context until a tool is first used, which softens but doesn't eliminate the cost.
• Every file the agent reads. A Read of a source file puts the whole thing into context, and it stays there.
• Every tool result. Test runs, grep output, terminal spew, build logs — all of it comes back as input tokens. A failing test suite that prints 8,000 lines just billed you for a small book.
• The entire conversation so far, re-sent on every turn. This one deserves its own section.

The resend nobody prices in

The Claude API is stateless. It does not remember your session between requests — nothing does. So on turn 2, the client sends turn 1 plus its response plus your new message. On turn 50, it re-sends turns 1 through 49 — every file read, every tool result, every diff — plus turn 50. The model re-reads the whole transcript every time, and every one of those re-read tokens is billed input.

The consequence: cost per turn grows roughly linearly with session length, and total session cost grows roughly quadratically. A message that cost half a cent at turn 3 can cost twenty times that at turn 60, for the same one-line question, because it's carrying sixty turns of freight. This is the single fact that explains most "why was my bill so high" tickets, and it isn't a Claude quirk — every stateful-feeling LLM product is a stateless API with a resend loop underneath.

Output: what you see, plus the thinking you don't

Output tokens are the expensive ones — five times the input rate across the current lineup ($5/$25 on Opus 4.8, $3/$15 sticker on Sonnet 5, $1/$5 on Haiku 4.5, as of July 2026). Output includes the text and code Claude generates, and thinking tokens: the internal reasoning the model does before answering. Two facts matter here. Thinking is billed at output rates and counts against max_tokens — an API response that dies with stop_reason: "max_tokens" and a truncated answer often means thinking consumed the budget before the answer did. And on current models the reasoning summary may not be displayed at all — Opus 4.8, Sonnet 5, and Fable 5 omit it by default — but the thinking still happened and is still billed. Invisible is not free.

Claude Code enables extended thinking by default because it measurably improves multi-step work, and the default budget can run to tens of thousands of tokens per request. On simpler tasks you can dial it down: lower the effort level with /effort or in /model, or adjust the thinking settings in /config. That's a genuine cost lever, not a superstition.

Prompt caching rewrites the math

Prompt caching is why the resend loop doesn't bankrupt everyone. The API can cache a stable prefix of your prompt — system prompt, tool definitions, conversation history — and on the next request serve it at a fraction of the price. As of July 2026 the multipliers are: a cache write costs 1.25× the base input rate (2× for the 1-hour variant), and a cache read costs 0.1×. Writes are a premium; reads are a 90% discount. A single read already more than pays back the 5-minute write premium.

Claude Code manages caching for you, and in a healthy session almost all of that giant resend is served from cache. But the default cache lives for five minutes from last use. Step away for a coffee that runs long, come back, send a message — the cache expired, and the entire accumulated prefix is re-written at 1.25× instead of read at 0.1×. On a 150K-token session, that one cold turn costs more than a dozen warm ones. This is the counterintuitive result worth internalizing: an idle-then-resume rhythm can cost more than continuous work, because every idle gap past the TTL converts your next turn from a cheap read into an expensive re-write. Work in stints; don't drip-feed a huge session one message per ten minutes.

If you're calling the API from your own application on a VPS, you get none of this for free — and the classic self-inflicted wound is a timestamp or request ID interpolated into the system prompt, which changes the prefix bytes every request and silently disables caching. The tell is usage.cache_read_input_tokens sitting at zero across identical-looking calls.

The formula, with a worked example

Ignore anyone quoting a flat "a session costs $X." Sessions vary by two orders of magnitude. What holds is the formula:

turn cost = (uncached input      x base input price)
          + (cache writes        x 1.25 x base input price)
          + (cache reads         x 0.10 x base input price)
          + (output incl. thinking x output price)

session cost = sum over all turns

Worked example on Claude Opus 4.8, which as of July 2026 is $5 per million input tokens and $25 per million output. A mid-session turn carrying 80,000 tokens of accumulated context: 75,000 read from cache, 3,000 newly written, 2,000 uncached fresh input, 1,500 output tokens including thinking.

• Cache reads: 75,000 × $0.50/M = $0.0375
• Cache writes: 3,000 × $6.25/M = $0.019
• Uncached input: 2,000 × $5/M = $0.010
• Output: 1,500 × $25/M = $0.0375

About $0.10 for the turn; fifty turns like it, around $5. Now the same turn after the cache expired: the full 80,000 tokens re-written at $6.25/M is $0.50 before output — roughly five times the whole warm turn, for identical work. That gap is the entire caching story in one number.

For calibration rather than prediction: Anthropic's published figures for enterprise Claude Code deployments, as of July 2026, average about $13 per developer per active day — $150–250 per month — with 90% of users staying under $30 a day. Your mileage is a function of model choice, session hygiene, and codebase size, which is exactly why the levers below matter.

Seeing your own usage

In Claude Code, the command is /usage (/cost still works — it's an alias). The Session block at the top shows token statistics and a locally computed cost estimate for the current session; on subscription plans the same screen shows your plan-limit bars and a breakdown attributing recent usage to skills, subagents, plugins, and individual MCP servers. For authoritative billing on API accounts, the usage page in the Claude Console is the source of truth — the CLI figure is an estimate. /context draws a colored grid of what's occupying the context window — system prompt, tools, MCP definitions, files, history — and is the fastest way to spot a bloated CLAUDE.md or a chatty MCP server; pass all to expand the full per-item breakdown.

From the API, every response tells you exactly what happened:

response = client.messages.create(model="claude-sonnet-5", max_tokens=2048,
                                  messages=messages)
u = response.usage
total_prompt = u.input_tokens + u.cache_creation_input_tokens + u.cache_read_input_tokens
print(f"uncached={u.input_tokens} written={u.cache_creation_input_tokens} "
      f"read={u.cache_read_input_tokens} output={u.output_tokens}")

Note that input_tokens is only the uncached remainder — the true prompt size is the sum of all three input fields. An agent that ran for an hour showing input_tokens: 4000 isn't cheap; the other 200,000 tokens were served from cache. To estimate before you send, use the token-counting endpoint — it's free to call, sits on its own rate limit, and counts with the tokenizer of whichever model you name (treat the result as a close estimate; billing reflects the real request):

count = client.messages.count_tokens(model="claude-sonnet-5",
                                     messages=[{"role": "user", "content": big_file}])
print(count.input_tokens)

Never tiktoken, for the reason above.

Subscription plans versus pay-as-you-go

The mechanics in this guide are identical everywhere; only the settlement differs. With an API key, Anthropic bills pay-as-you-go, per token, at the published rates — every number above is real money. On a Claude subscription (Pro, Max, Team, Enterprise), Claude Code usage draws from your plan's included allowance instead: as of July 2026 that's a rolling five-hour session window plus a weekly window, shared across models and with claude.ai chat, and the /usage dollar figure is informational rather than a bill. Exhaust a window and you'll see "You've hit your session limit" or "You've hit your weekly limit" with a reset time — and switching models with /model won't restore access, because the windows are shared across models. Plans can optionally enable usage credits, managed with /usage-credits, to buy usage past the ceiling. I deliberately won't print the plan quotas: they're the most volatile numbers in this whole topic, so check claude.com/pricing and your own /usage bars instead. The token mechanics still matter on a subscription — a wasteful session burns your window exactly the way it would burn dollars. Which plan makes sense is its own decision.

The levers that actually work

• Scope what the agent reads. "Fix the validation bug in auth.py" reads one file; "improve this codebase" reads forty. Keep CLAUDE.md lean — it's loaded into every session, so hold it to essentials — and move workflow-specific instructions into skills that load on demand.
• Clear and compact. /clear between unrelated tasks — stale context is re-sent, and re-billed, on every subsequent message. Within one long task, /compact Focus on the failing tests and the diff summarizes history down and keeps you off the quadratic curve.
• Right-size the model. Sonnet handles most coding at $2/$10 per million tokens on introductory pricing as of July 2026 ($3/$15 sticker, versus Opus at $5/$25), and Haiku at $1/$5 is the right tool for mechanical subagent work like log triage. /model switches mid-session.
• Pre-filter verbose output. A hook that greps a test run down to failures before Claude sees it turns 20,000 tokens of tool result into 300, and it does so on every future resend of that turn.
• Batch what isn't interactive. For your own API pipelines — classification, bulk review, nightly jobs — the Batches API runs the same models at 50% off in exchange for asynchronous delivery.
• Respect the cache clock. Work in continuous stints. A detached Claude Code session in tmux on a VPS costs nothing while idle — tokens are only spent when a turn runs — but the warm cache is what the idle time forfeits, and the next turn pays the re-write.

FAQ

How many tokens does a coding session in Claude Code use?

There's no fixed number — a single mid-session turn commonly carries tens of thousands of prompt tokens once files and history accumulate, and a working session runs into the millions, most served from cache at a tenth of the base rate. For calibration, Anthropic's published enterprise figures as of July 2026 average around $13 per developer per active day, with 90% of users under $30. Run /usage in your own session; five minutes of watching it beats any published average.

Do thinking tokens cost money even when I can't see them?

Yes. Thinking tokens are billed as output tokens — the expensive rate — and count against max_tokens, and current models bill them even when the interface omits the reasoning summary from display. If a response truncates with stop_reason: "max_tokens" before the visible answer finishes, thinking likely consumed the budget. In Claude Code, lower the effort level with /effort for tasks that don't need deep reasoning.

Why does a long Claude Code session get more expensive per message?

Because the API is stateless: every turn re-sends the entire conversation — every file read, tool result, and prior exchange — as billed input, so turn 50 carries turns 1 through 49 as freight. Prompt caching serves the repeated prefix at about a tenth of the base input price, but the prefix itself keeps growing, and any idle gap past the cache TTL converts the next turn into a full-price re-write. /compact shrinks the history; /clear resets it.

How do I check my Claude token usage and cost?

In Claude Code, /usage shows session token statistics, a local cost estimate, and plan-limit bars on subscriptions (/cost is an alias); /context shows what's filling the window. For authoritative API billing, use the usage page in the Claude Console. In your own code, read response.usage — summing input_tokens, cache_creation_input_tokens, and cache_read_input_tokens gives the true prompt size — and estimate ahead of time with the count_tokens endpoint, never with tiktoken.