Claude Code Token Usage: Read /usage, Context, Cache, and Cost Correctly
You are twenty minutes into a session. The conversation has grown, you have pulled in a few files, run some shell commands, and let a subagent handle a parallel task. Something feels heavy. You type /usage and a panel appears with seven or eight numbers: total cost, API duration, wall duration, lines of code changed, input tokens, output tokens, cache reads, cache writes. The numbers are real, but they do not all answer the same question, and reading them as a single "how expensive was this?" score will lead you to wrong conclusions.
This guide untangles what each field measures, why consumed tokens, current context, API cost, and plan allowance are four genuinely different things, and how to trace the sources that drive each one upward.
What /usage Actually Shows
Claude Code 2.1.208 exposes /usage as a session-local diagnostic panel. It renders without making a new model call, so opening it does not itself add to the numbers you are reading. In the tested version the displayed fields are:
- Total cost — the running API-dollar estimate for the session.
- API duration — time spent waiting for model responses.
- Wall duration — elapsed clock time for the session.
- Code changes — lines added or removed (a productivity proxy, not a token metric).
- Input tokens — tokens sent to the model across all turns.
- Output tokens — tokens generated by the model across all turns.
- Cache reads (sometimes labeled cache read tokens) — prompt content served from the prompt cache rather than reprocessed.
- Cache writes (sometimes labeled cache write tokens) — prompt content written into the prompt cache for future reuse.
These are cumulative session totals, not per-turn snapshots. A clean /usage check at the start of a session and again after a bounded block of work gives you the delta for that block—a more actionable unit than a session total alone.
The Four Things People Mean by "Token Usage"
The most common source of confusion is that "tokens" gets used to mean four separate concepts that behave differently and should be managed differently.
1. Consumed tokens — what the API billed
Every turn in a session sends an input prompt and receives an output. The API meters both. The input tokens and output tokens in /usage are the running sum of those charges. Once a turn completes, those tokens are consumed regardless of what happens next. Compacting the context, starting a fresh session, or deleting local files does not retroactively subtract from consumed tokens.
2. Active context — what the model is currently aware of
The model can only use what fits inside the context window right now. Active context is the working material available on the current turn: retained conversation, included file content, tool results, system instructions, and other injected content. It can shrink after compaction or a fresh conversation, while prior usage does not rewind.
3. API-dollar estimate — the cost figure
The cost shown in /usage is the session cost view reported by Claude Code. It is useful for comparing sessions with similar task shapes, but it is not a view of your remaining subscription allowance. Use the current official billing documentation for account-level interpretation.
4. Plan allowance — your subscription capacity
If you access Claude Code through a subscription plan, plan allowance and the /usage cost view answer different questions. The tested /usage panel did not display remaining allowance. /usage-credits, organization analytics, and other account surfaces were not tested here; verify their current availability and meaning in official documentation. Do not derive remaining subscription capacity from the session cost field.
Cache Reads and Writes: Not Ordinary Input
Prompt caching is one of the more confusing fields in /usage because the word "tokens" appears in all four input-output-cache-read-cache-write rows and it is tempting to add them together.
Cache writes record prompt content written to the prompt cache for possible reuse on later turns. Their cost and retention behavior should be read from the current official prompt-caching documentation.
Cache reads record prompt content reused from the cache. They appear as a separate accounting category from ordinary input; use the current official pricing documentation when comparing their cost.
The diagnostic implication is directional: cache reads show reuse, while cache writes show content prepared for possible reuse. A pattern of repeated writes with little reuse is worth investigating, but /usage alone does not identify the exact cause.
Cache reads are not ordinary new input. Keep input, cache-read, and cache-write fields separate and follow the official accounting definitions rather than inventing a combined total.
What Compaction Does and Does Not Do
Context compaction in Claude Code summarizes or truncates older conversation history to reclaim context-window space. After compaction:
- Active context becomes smaller. The model works from the summary rather than the full history.
- Consumed tokens do not decrease. Every turn that occurred before compaction has already been billed. The API does not issue token refunds.
- Future turns become cheaper because the input prompt is shorter.
Compaction is a forward-looking tool, not a retroactive one. Use it when a session is approaching context limits or when historical detail is no longer needed. Starting a fresh session resets the conversation history, while startup instructions or project context may still load. The tradeoff is that you reintroduce any files, task description, or prior decisions the next phase requires.
What Drives Usage Upward: A Source-by-Source Trace
Understanding the contributors matters because each one has different levers.
Conversation history
Retained user messages and model responses grow the conversation layer. Compaction, caching, and context management affect what the next request carries, so use /usage as a reported total rather than assuming a simple linear formula.
Files read into context
Files and excerpts read for the model can enter its working context. Large or repeatedly returned content can increase input, but exact token impact depends on what the active prompt retains and how caching applies.
Command and tool output
Shell commands, test runners, linters, and build outputs produce text that Claude Code often includes in the prompt so the model can reason about results. Unbounded command output—a full test suite log, a verbose dependency tree, a large diff—adds tokens that may not all be necessary for the model's next decision.
MCP tool definitions and results
Model Context Protocol servers expose tools to Claude Code. Their tool definitions consume context, although current loading behavior can vary by configuration and version. MCP tool results can add further content after invocation. Auditing which servers and tools are needed for the current task is a useful diagnostic step.
Skills and plugins
Skills and plugins can add instructions, tool definitions, or returned content to a session. The exact loading behavior varies by feature and version. Review what an extension contributes, and remove or disable what the current task does not need.
Subagent returns
When Claude Code uses subagents or delegated work, returned results can become input to the parent conversation. A detailed report adds more context than a concise status update. Exact usage attribution between parent and subagent was not tested here; the practical control is the size and relevance of what comes back.
A Bounded Comparison Method
Exact per-feature attribution is not reliably achievable through /usage alone. What is achievable is a bounded before-and-after comparison that isolates one factor at a time.
Step 1: Establish a clean baseline. Start a fresh session with no files open, no MCP servers active, no subagents running. Run a representative task—a short coding problem, a file analysis, a multi-turn debugging exchange—that you can repeat. Record the /usage delta for input tokens, output tokens, cache reads, and cache writes at the end.
Step 2: Change one factor. Add one MCP server, enable one Skill, include one additional file in context, or allow a subagent to return a full transcript instead of a summary. Keep the representative task identical or as close as practical.
Step 3: Repeat and compare. Run the same task and record the /usage delta. Treat the difference as directional evidence, not exact attribution, because model output and cache behavior vary.
This method does not produce lab-grade measurements. Model output length varies, cache behavior changes, and "the same task" is never perfectly identical. It can still show whether an integration, file pattern, or return format is associated with a consistent increase worth investigating.
A Diagnostic Walkthrough
Here is a composite example of how to use /usage to investigate a session that has grown more expensive than expected.
You are working on a medium-sized codebase refactor. After an hour, /usage shows input tokens significantly higher than a comparable session last week. Output tokens are similar. Cache reads are low.
Check cache health first. Low cache reads with high input suggests the prompt is not hitting cache effectively. A common cause is that a file being read on every turn is being modified between turns, invalidating the cached version. Identify which files are repeatedly read and whether they change frequently.
Audit MCP servers. Run a mental inventory of which MCP servers are active. If you are using a documentation MCP, a database MCP, and a file-search MCP, their combined tool definitions may be adding several hundred tokens to every input. Disable any server whose tools you have not used in the current task phase.
Inspect subagent returns. If subagents are involved, consider what they are returning. A subagent asked to "analyze the test suite" might return a full analysis document when the parent session only needs a pass/fail judgment and a list of failed test names. Tighten the subagent's output instructions.
Check for large files. Use a quick shell command to check the size of files you have asked Claude Code to read. A configuration file or schema file that is unexpectedly large is a common culprit.
Compare the delta, not the total. Once you have made adjustments, start a new session and run a comparable task segment. Compare the /usage delta from that segment against your baseline. If input tokens dropped, your changes are working. If they did not, the driver is elsewhere.
Reduction Tactics That Preserve Work Quality
The goal is not to minimize tokens at the expense of useful work. It is to avoid paying for context that does not contribute to the model's quality of reasoning.
Narrower file reads. Instead of reading an entire 2,000-line module to answer a question about one function, read the relevant section. Claude Code supports targeted reads; use them when you know which portion matters.
Summarized command output. For long-running commands whose full output is not needed, pipe output through head, tail, grep, or a purpose-built summary command before Claude Code sees it. A 50-line filtered error log is more useful than a 2,000-line verbose build log for most diagnostic purposes.
Fewer redundant MCP tool definitions. Audit your MCP configuration at the start of a project phase. Disable servers that are not relevant to the current work. Their tool definitions occupy prompt space on every turn even when no tool from that server is called.
Deliberate subagent return design. When orchestrating subagents, specify the format and maximum size of what they should return. "Return a JSON object with keys: status, failed_tests (list of names only), next_suggested_action (one sentence)" produces a smaller, more parseable return than "return your full analysis."
Compaction and fresh sessions at task boundaries. When a phase of work is complete and the next phase is substantially different, compaction or a fresh session resets active context. The work is preserved in files and version control; the model does not need the full history of how you got there to continue productively.
Watch cache patterns without guessing their cause. If cache writes repeatedly rise while reuse stays low, compare what changed between turns. /usage can reveal the pattern, but not which prompt segment caused it.
What This Number Means / Does Not Mean
| Field | What it measures | What it does not measure |
|---|---|---|
| Input tokens | Total tokens sent to the model this session | Current context window occupancy; plan allowance consumed |
| Output tokens | Total tokens generated by the model this session | Response quality or relevance |
| Cache reads | Prompt tokens served from the cache at reduced rate | Tokens that cost nothing; ordinary new input |
| Cache writes | Prompt tokens stored in the cache for reuse | Guaranteed future savings (depends on cache hit rate) |
| Total cost | Session cost view reported by Claude Code | Subscription quota remaining |
| API duration | Time the session spent waiting for model responses | Wall-clock productivity or work quality |
| Wall duration | Elapsed session time | Time spent on model calls specifically |
| Code changes | Lines of code added or removed | Token efficiency; whether changes were correct |
Official References
Reading /usage With the Right Questions
The numbers in /usage are Claude Code's reported session view. The diagnostic error is asking a field a question it cannot answer: asking input tokens whether you are close to a plan limit, asking total cost whether context will soon overflow, or asking cache reads whether the broader workflow is efficient.
The productive frame: input tokens tell you what Claude Code reports as session input; active context describes what the model can use right now; total cost is the session cost view; plan allowance is a separate account-capacity question. Compaction can shrink active context without undoing prior usage. Cache fields remain separate accounting categories. Subagent returns may add parent context, while exact attribution was not tested here.
Open /usage at the start of a task phase and at the end. The delta tells you what that phase cost. Change one thing, run the phase again, compare the delta. That is the measurement discipline that turns seven numbers into actionable guidance.