Pull up /usage after what felt like a light Claude Code session, and the numbers can be surprising. Your prompts were short. The task seemed simple. So where did all those tokens come from?
Often, not from what you typed, but from everything Claude Code had to process alongside it.
Each request can include the system prompt, project instructions, tool definitions, and relevant conversation history. Prompt caching makes repeated content much cheaper, but as a session grows, that background context can still account for a large share of the tokens associated with each turn.
A bloated CLAUDE.md, a long-running session, or changes that invalidate the prompt cache can make an otherwise simple request noticeably more expensive without changing the task itself.
In this post I have tried to walk through few key areas. What’s actually in each request, which parts grow fastest, and how to control them, from caching and compaction to thinking budgets and the stale-session trap.
Think of every request as three stacked layers:
Claude Code uses prompt caching to avoid re-billing the same content repeatedly. Cached input tokens cost roughly 10% of the standard input token rate. That’s a real discount, but it only kicks in when the cached content stays stable. Because prompt caching depends on matching prefixes, changes near the beginning of the prompt can invalidate cached content that follows. Some modern Claude Code features, such as deferred MCP tool , are specifically designed to reduce unnecessary cache invalidation.
Some changes still create a cold cache. Switching models or effort levels does, and enabling fast mode for the first time in a conversation can as well. MCP changes are more nuanced because Claude Code can defer tool definitions, allowing some server changes without invalidating the existing cached prefix.
The highest-leverage optimizations target what stays the same across turns, not what changes. Keep the early layers small and stable, and the cache does the work.
CLAUDE.md loads at every session start. It's the single most overlooked token sink in a typical Claude Code setup, because it grows organically as teams add instructions over time.
Anthropic’s official cost guidance recommends keeping CLAUDE.md under 200 lines.
The rule: CLAUDE.md should contain only what's true for every task in this project. Anything workflow-specific belongs in a skill.
Unlike CLAUDE.md, a skill’s full instructions load only when the skill is invoked. Its short description may remain in the base context so Claude knows when to use it. A "PR review checklist" or "database migration procedure" sitting in CLAUDE.md loads on every session. The same content as a named skill loads only when you call it. For a project with five specialized workflows, that gap compounds quickly.
Path-scoped rules give you similar control at a finer grain. Rules without a paths: frontmatter key load at every session start regardless of what you're working on. Add a paths: key and the rule only enters context when Claude touches a matching file:
---paths: - "src/api/**"---Always validate request bodies against the Zod schema before processing.
This rule’s body doesn’t consume context unless Claude works with a matching file, such as one under src/api/. Audit your rules directory, not just CLAUDE.md.
MCP tools still add context overhead, but modern Claude Code defers many MCP tool definitions by default. Connecting or disconnecting a deferred server generally preserves the existing cached prefix. A cache rebuild becomes relevant when those tool definitions are loaded into the prompt upfront.
Disabling servers you won’t use in a session is cleaner. Run /mcp and disconnect what doesn't apply.
Where you have a choice, prefer CLI tools over MCP equivalents. Running gh or aws from Bash adds zero per-definition overhead to the system prompt.
Model and mode stability matters here too. Switching models or changing effort level causes a cache miss. Enabling fast mode for the first time in a conversation also causes a cache miss, though later fast-mode toggles can preserve the cache. Per the prompt caching docs, these are explicit invalidation triggers. Pick your model at the top of a session and stick with it. If you use a pattern like Opus for planning and Sonnet for execution, know that each switch starts a cold cache, so the output token savings come with a re-read cost on every transition.
The conversation layer always grows. In a long session, it’s often what dominates the bill.
Three commands manage it:
One caveat on compaction: don’t compact constantly. The rebuild turn is real money. The savings only pay off if the session continues long enough afterward. Compact at genuine task boundaries, not reflexively.
Walk away from a session long enough and the cache can expire. When you return, the old prefix can no longer be served at the cheaper cache-read rate, so Claude must reprocess the context and re-establish the cache. That makes the first turn back substantially more expensive than a normal warm-cache turn. A single return to a stale long session can be the most expensive request you send all day.
If you know you’re leaving a long session and expect to return later, consider running /compact while the cache is still warm. That leaves a much smaller conversation to restore when you come back. You pay the compact cost once, and the next turn back starts from a much smaller cached prefix. Source: Claude Code prompt caching docs.
When you’re doing research or read-only exploration across a big codebase, use /graphiphy. It builds a lightweight graph of your codebase structure so Claude navigates by index rather than reading every file. Though if you have a write heavy repo, you might find yourself with outdated graph and need to update the graph often.
Github Project: https://github.com/safishamsi/graphify
This one isn’t just about tokens. It’s about comprehension.
LLM output is verbose by default. Long paragraphs, hedged sentences, qualifications on qualifications. /caveman forces Claude to respond in short, direct sentences. No filler. No AI prose.
The token saving could be real for some users as fewer output tokens per response. But the bigger win is speed: you read faster, catch mistakes faster, and course-correct faster. When agents talks like a caveman, you spend less time parsing and more time building.
Github Project: https://github.com/juliusbrussee/caveman
Both are third-party tools rather than Anthropic products. Review their code, permissions, maintenance status, and security implications before installing them.
The /usage command shows usage, cache behavior, and estimated cost. Press d for the 24-hour view or w for the 7-day view. Run it when your token use or bill surprises you. To inspect what is actually occupying the context window — such as tools, project instructions, and conversation history — use /context.
Two categories of expensive output have structural fixes.
Reserve high-effort mode for tasks that need deep reasoning: architectural decisions, debugging subtle concurrency issues, evaluating complex tradeoffs. For “add a null check to this function,” a low thinking budget is fine and the quality difference is negligible.
Lower the effort level with /effort command
/effort low
Claude can also burn tokens on tool output you never needed. A test command that dumps thousands of log lines into the conversation can consume a large amount of context even if only a handful of lines contain useful errors.
The simplest fix is to reduce noisy output at the command itself:
npm test 2>&1 | grep -A 5 -E '(FAIL|ERROR|error:)' | head -100
For repeated workflows, you can automate this with a PreToolUse hook. The hook runs before a tool call executes and receives the proposed tool input as JSON. It can inspect the Bash command and return a modified updatedInput before execution.
For example, a hook script could append an output filter to selected test commands:
#!/bin/bashINPUT=$(cat)COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command')if echo "$COMMAND" | grep -qE '^(npm test|pytest|go test)'; then FILTERED_COMMAND="$COMMAND 2>&1 | grep -A 5 -E '(FAIL|ERROR|error:)' | head -100" jq -n \ --arg command "$FILTERED_COMMAND" \ '{ "hookSpecificOutput": { "hookEventName": "PreToolUse", "permissionDecision": "allow", "updatedInput": { "command": $command } } }'fi
You can then register that script as a PreToolUse hook for Bash commands.
Be careful with aggressive filtering: removing too much output can hide information Claude needs to diagnose a failure. A safer pattern is to filter commands where the useful signal is predictable, such as test failures or repetitive build logs.
Another option is to delegate log-heavy exploration to a subagent. That keeps large intermediate outputs out of the main conversation context while letting the subagent return only the useful findings.
Some optimizations are purely mechanical, with no quality tradeoff at all:
Most token waste in Claude Code comes from what you pay to load, not from what you ask Claude to do. An oversized CLAUDE.md, unscoped rules, default thinking budgets, and mid-session model switches all generate charges before you type a single word.
Start here: use /usage to understand token consumption, cache behavior, and cost, then use /context to inspect what is occupying the context window. If tool definitions take up significant space, review your MCP connections and tool configuration. If project instructions are large, audit CLAUDE.md against the 200-line guideline and move specialized workflows into skills or scoped rules. If conversation history dominates, consider clearer task boundaries, /clear, or strategic use of /compact.
One honest caveat: skills, hooks, and scoped rules add maintenance surface. For a solo developer on a small codebase with a modest monthly spend, the setup overhead may not be worth it. These tools pay off at team scale and on projects where sessions regularly run long. Know your situation before optimizing for it.
The numbers in /usage tell you whether you have a real problem. Start there.
A Few Tips to Cut Claude Code Token Costs was originally published in Towards AI on Medium, where people are continuing the conversation by highlighting and responding to this story.