Claude Code Token Usage: How It Works and How to Cut It

If you're searching for how to claude code tokens work, you’re likely staring at a surprising bill and wondering where all those millions of tokens went. The real story isn’t just the context window you see—it’s the billed tokens that quietly add up from cache operations, tool schemas, and a conversation history that never stops growing. At techpotions, we build AI‑powered dev tooling, and we’ve watched teams burn through credits simply because the invisible overhead of CLAUDE.md, MCP tool definitions, and large file reads wasn’t obvious. This guide explains how token accounting actually works, shows you exactly where leaks hide, and gives you the settings that cut spend without neutering Claude’s ability to understand your codebase.

How Claude Code Token Usage Works: Context Window vs. Billed Tokens

The context window is the session’s working memory—everything Claude can see at one moment. Official docs break it down: the system prompt, your CLAUDE.md, tool schemas from connected MCP servers, conversation history, and the contents of every file that’s been read or edited. When the window fills, Claude Code compacts: it summarizes the conversation, drops stale data, and re‑reads up to five recently modified files.

But the bill doesn’t follow the context window beat by beat. You’re charged for:

• Input tokens: everything Claude processes, including tool results and system prompt again each turn.
• Output tokens: code, explanations, and tool calls Claude generates.
• Cache creation tokens: when a large chunk of data is stored in the prompt cache (a one‑time write, costing a premium).
• Cache read tokens: when that cached chunk is reused in a later turn (far cheaper per token).

The gap bites: a 10 000‑token file read into the context window also triggers a cache write if it’s new. But if the file gets evicted from cache before your next turn, you’ll pay for the full input tokens again—not just a cheap cache read. This is why monitoring both the context gauge and the /usage breakdown matters.

The Hidden Token Drains Inside Your Code Sessions

We’ve seen sessions where the sum of CLAUDE.md, MCP schemas, and a single eslint output took more than 60 % of the context budget before any real code was written. The result wasn’t a better outcome—just faster compaction and a fatter bill.

How to Measure Token Usage Per Session

The fastest way to see what’s actually hitting your wallet is the /usage command. It prints a session block with real‑time stats.

> /usage

=== Session Usage ===
Input tokens:      127,458
Output tokens:       3,211
Cache creation:     21,000
Cache read:         84,200
Total cost:         $0.16

The cost measurement uses the model’s pricing table and breaks down input, output, and cache operations. Keep an eye on Cache creation—if it’s climbing rapidly, large fresh data is being injected often. If Cache read is low relative to Input tokens, you’re probably paying for the same files multiple times because the cache is too small or evicting aggressively.

Settings That Cut Spend Without Cutting Quality

Many of the speed knobs we tuned to fix sluggishness also slash token waste. Think of them as two levers on the same machine.

• Trim the permanent overhead. Keep CLAUDE.md short and remove any MCP servers you aren’t actively using. A quick export CLAUDE_MCP_SERVERS=critical-server before starting a session can chop thousands of tokens.
• Cap tool output. Set MAX_TOOL_OUTPUT=60000 (or the CLI flag --max-tool-output 60000) so that rogue commands don’t dump their entire history into your conversation. This costs you no code quality, only noise.
• Use .claudeignore aggressively. Exclude node_modules, dist, .venv, and any other heavyweight directories. Claude Code won’t read them into context, and they won’t appear in grep results—doubly saving tokens.
• Compact with care. The /compact command isn’t free; it enforces re‑reads of up to five recently edited files. But if you’re already sitting at 90 % context, a proactive compact prevents an emergency one that might drop critical context. Use it before starting a new major task.
• Monitor with --verbose. Start a session with claude --verbose to see token counts per step. You’ll quickly spot the moment that 12 000‑token file sneaked in.

How Cache Reads and Writes Affect Your Bill

Claude Code caches system‑level prompts, CLAUDE.md, MCP definitions, and any file contents it reads. A cache write costs roughly 1.25× the normal input price, while a cache read is 10× cheaper. So the first time you read a 20 000‑token module, you pay a premium—but every subsequent turn re‑reading that same module costs almost nothing.

The catch? The cache has a finite size, and compaction flushes it. If you read twenty different large files in one session, the cache fills and older entries get evicted. The next time you reference an evicted file, you’re paying full input price again, effectivelyduplicating the cost of that read. Structuring your workflow to reuse a smaller set of files keeps cache read counts high and your bill low.

The CLAUDE.md Cost Trap (and How to Avoid It)

A well‑intentioned CLAUDE.md is the silent budget‑burner we see most often. After adding a detailed 4 500‑token code‑style guide, the context window immediately lost that space. The cache write was a one‑time hit, but the ongoing cost came from earlier compaction. With less room for real code, Claude was forced to compact after only a few turns and re‑read files it had already processed—each re‑read triggering a fresh cache write. The end result: a 30 % jump in total session tokens, all because a document that was meant to help made the session less efficient.

The fix: treat CLAUDE.md as a precision instrument. If a rule isn’t actively preventing a mistake you’ve encountered, drop it. Prefer short, actionable bullet points over prose paragraphs. A 600‑token CLAUDE.md usually delivers 90 % of the value at a fraction of the footprint.

Connecting Token Usage to Speed

Every token you shave from the permanent overhead reduces the payload Claude must process on each turn. That directly improves response latency—the same connection we explored when fixing slow Claude Code sessions. The number‑one takeaway from that post applies here too: less context to scan means faster model inference and a lower bill in one stroke.

FAQ

Why does my Claude Code bill spike after adding a large CLAUDE.md?

CLAUDE.md is injected into the system prompt, so it occupies context window space permanently—and incurs a one‑time cache write plus a small read cost on every turn. If it’s verbose (e.g., a 5 000‑token style guide), it can push you closer to compaction, which forces expensive re‑reads of recently touched files. Trim it to only the instructions Claude actually needs, not an aspirational document.

Does lowering the context window slider actually save money?

Yes, but not instantaneously. Reducing the context window limits the maximum tokens Claude can hold at once, which can reduce per‑turn costs—especially if your sessions rarely fill the default window. However, a tighter window forces more frequent compaction and re‑reads of files, which may increase total tokens in a long session. Start by trimming overhead (CLAUDE.md, MCP schemas) rather than lowering the hard limit.

How can I tell if prompt caching is working for my session?

Check the Session block in /usage. Look for the cache_creation and cache_read lines. If cache reads are high relative to total input tokens, caching is saving you money. If you see very few cache reads but every large file is being counted as input tokens, the cache may be evicting too aggressively. You can also watch the context gauge in the UI—an always‑full bar often signals caching isn’t helping enough.