Token usage
Claude Code token usage: what counts and how cache reads work
Last reviewed July 2026.
Short answer: Claude Code token usage is everything the model processes in your sessions — prompts, replies, tool output, file reads, and sub-agents — not just the lines you type. On the API, cache reads usually cost less per token than fresh input; on a subscription they still draw from your usage limits, often more lightly per token when caching applies. Exact multipliers change; as of July 2026, treat cache hits as real but discounted usage, and verify against Anthropic’s docs.
What counts
Claude Code does not meter “minutes in the terminal.” It meters tokens that flow through the model:
- Your user messages and instructions
- Model responses
- Tool and shell output pulled into context
- File and directory contents the agent reads
- Sub-agent or nested-agent context when you use those features
A short clarifying question is cheap. A long agent loop that reads half the repo and pastes a full test log is expensive — and that cost compounds because prior context is typically still present on later turns.
For dollar estimates on API keys (not subscription caps), use the free Claude token calculator.
Cache-read weighting (hedged)
Prompt caching lets unchanged prefix content be read from cache on later requests. As of July 2026, Anthropic’s API prices cache hits / refreshes well below base input (for example on the order of ~0.1× the input rate on current published tables — confirm live numbers). That means:
- Cache reads still count as usage.
- They usually draw less budget per token than fresh uncached input.
- Cache writes can cost more than base input in the window when the cache is created.
On a Claude Code subscription, you do not see a line-item invoice per request, but the same underlying mechanics apply: cached prefixes are cheaper to re-process than re-sending everything as fresh tokens. Do not assume cache reads are free, and do not ignore them when forecasting a weekly limit.
What burns the most in practice
From how agent CLIs behave (and from what local transcript audits typically surface):
- Verbose tool output — builds, tests, stack traces dumped in full
- Repeated file reads — the same modules pulled in across many turns
- Wide exploration — directory dumps and speculative reads that never get used
- Long-lived sessions — context that never gets cleared while you keep working
Windows and WSL users hit the same categories; transcript paths differ — see tracking usage in WSL2 and the Windows hub.
How to measure your own usage
Claude Code stores session transcripts locally. The free hypermile-audit CLI reads those files on your machine and prints a plain-English category breakdown — tool output vs file reads vs conversation vs sub-agents. Nothing is uploaded; it is open source.
Once you can see the mix, the fixes get concrete: truncate logs before they hit context, narrow reads, end exploratory sessions sooner. Hypermile automates the noisy-trim step on Windows, macOS, and Linux and forecasts when you will hit the cap.
Next steps
Run the audit below, then download Hypermile. For the caps those tokens draw against, read Claude Code usage limits. For API dollar math, open the token calculator. For why those tokens pile up in the first place, see the context window and what compacting costs.
Frequently asked questions
What counts toward Claude Code token usage?
Everything that passes through the model in a turn: your messages, the model’s replies, tool results, file contents pulled into context, and sub-agent work. Longer context costs more because prior turns are typically re-sent or re-processed as the conversation grows.
Do cache reads count toward Claude Code usage?
Yes, but usually at a lower effective weight than fresh input when prompt caching applies. Cache hits are still usage — they are just cheaper per token on the API and lighter on the wallet. On a subscription, treat them as real drawdown that is often smaller per token than uncached input; exact weighting can change — verify against Anthropic’s current docs.
Why does Claude Code token usage spike on agent runs?
Agent runs multiply tool calls and file reads. Each result lands in context and is often carried into later turns, so a noisy build log or a wide directory read keeps costing you after the moment you captured it.
How can I see my own Claude Code token usage?
Claude Code writes local session transcripts. A local audit tool can read them and break usage into categories (tool output, file reads, conversation, sub-agents) without uploading anything. That breakdown is the starting point for cutting waste.