# How to Reduce Claude Code Token Usage

> Claude Code burns tokens on eager file reads, unfiltered tool output, bloated MCP manifests and runaway transcripts. Here's how to cut each one without losing quality.

Source: https://tokenade.net/en/articles/reduce-claude-code-token-usage · Updated: 2026-10-07

## How do you reduce Claude Code's token usage?

You reduce Claude Code's token usage by targeting the four sources that actually dominate cost: eager whole-file reads, raw command output dumped straight into the transcript, the MCP tool manifest re-sent on every turn, and a growing conversation that re-bills every past read. Tighten each source and the cost drops sharply — with no loss in output quality, because you're trimming noise, not signal.

This is the Claude Code–specific companion to [How to reduce AI coding agent token usage](https://tokenade.net/en/articles/reduce-ai-coding-agent-token-usage). If you want the agent-agnostic picture first, start there. Here we map those same levers onto Claude Code's concrete behaviour: how it reads files, which commands it tends to run, how the transcript grows, and what the `/compact` command actually does.

## Why does Claude Code burn so many tokens?

Claude Code burns tokens primarily because it reads more than it needs, and then re-reads it on every subsequent turn. The root cause is architectural: on each step of an agentic loop, Claude re-reads the entire conversation history plus any tool results. That means any oversized read you incur early is paid again on every turn that follows.

Four specific patterns drive most of the bill:

**Eager whole-file reads.** When asked to "understand" a module, Claude Code defaults to reading the full file. A 500-line TypeScript file is roughly 5,000–7,000 [tokens](https://tokenade.net/en/glossary/token) — and Claude Code may read a dozen files before it writes a single line of code. If the [context window](https://tokenade.net/en/glossary/context-window) carries those reads for 20 turns, you've paid for each of them 20 times.

**Unfiltered tool output.** Claude Code runs shell commands — `git status`, `npm test`, `tsc --noEmit`, build tools — and the raw output flows straight into the transcript. A failed `npm test` run can emit 15,000 tokens of stack traces, passing-test checkmarks and timing tables. Claude Code needed about 50 tokens of it: the failing test name and the broken assertion. Everything else is cargo.

**The MCP manifest.** Every MCP server you've connected puts something into the context on every turn, whether or not any tool is used. Recent Claude Code versions defer full tool schemas by default, so what rides along is the tool names and server instructions, but servers marked `alwaysLoad` and setups where tool search is off still pay for every full definition. That constant overhead accumulates silently over the whole session. See [MCP](https://tokenade.net/en/glossary/mcp) for how the protocol works and [Best MCP servers for Claude Code](https://tokenade.net/en/articles/best-mcp-servers-for-claude-code) for which servers are worth keeping.

**An unbounded transcript.** Claude Code sessions that sprawl across several tasks or re-visit the same files repeatedly can build up transcripts that cost more to re-read than the original work. Each new turn pays for every prior turn's context.

Understanding which pattern dominates your workflow is step one. Run `/context` to see what is filling the window and `/usage` to see the session's token usage ([Claude Code cost docs](https://code.claude.com/docs/en/costs), as of October 2026) — the answer usually points immediately at the right lever.

## What are the biggest levers for Claude Code specifically?

The biggest levers are file retrieval, output filtering and MCP pruning — roughly in that order for most Claude Code sessions.

### Make Claude Code search instead of read

The default pattern — "read `src/auth/login.ts`" — hands Claude a whole file when it needed one function. The better pattern is to direct Claude Code toward the specific symbol: "find the function that validates the JWT and show me its signature." When retrieval is working well, Claude Code reads 2,000 tokens instead of 20,000.

In practice this means:
- Ask Claude Code to locate the relevant symbol first, then read that function body
- Avoid phrases like "read the repo", "check all the files in X", "go through the codebase" — these are open-ended file-read instructions
- When starting a new task in a large repo, describe the *behaviour* you want to change ("where do we handle login errors") rather than the *files* you think are involved

Semantic retrieval — finding code by meaning rather than file name — is where tooling helps most. [Tokenade](https://tokenade.net/en) installs into Claude Code in one command and replaces broad file reads with ranked symbol lookups, so Claude Code reads the three relevant chunks instead of every file in the directory.

### Filter command output before it enters the transcript

This is often the highest-yield single change for projects with active test suites or build pipelines. The goal is to intercept tool output between the shell and the transcript, and hand Claude Code only what it needs.

Concretely:
- Prefer terse command flags: `git status --porcelain` over bare `git status`, `jest --silent` to suppress passing-test noise, `tsc --noEmit 2>&1 | grep error` to surface only type errors
- For build systems, capture only the error lines rather than the full log
- For test runners, surface only failing tests with their assertion, not the full runner output

[Output filtering](https://tokenade.net/en/glossary/output-filtering) applied systematically to build and test commands can cut token usage by an order of magnitude on failure-heavy sessions, because those commands tend to produce the most verbose output and get run the most often.

### Prune the MCP manifest

Every MCP server connected to Claude Code adds something to every turn's context, whether or not you call any of its tools. If you've assembled a rich MCP setup over time — file systems, databases, external APIs — that overhead can be substantial.

The topic moved since this guide first came out. As of October 2026, Claude Code's [MCP tool search](https://code.claude.com/docs/en/mcp) is on by default for Claude 4.5-generation models and later: tool definitions are deferred, only tool names and server instructions enter context, and a full schema loads when Claude actually reaches for that tool. Three cases still load everything upfront: a server you marked `alwaysLoad: true`, `ENABLE_TOOL_SEARCH=false`, and an `ANTHROPIC_BASE_URL` pointing at a non-first-party proxy, where Claude Code turns tool search off unless you set the variable explicitly. If you route Claude Code through a gateway, check this first.

Deferral shrinks the per-tool cost; it doesn't make a server free. Audit what you actually use per session with `/mcp` and disable the rest. Tools whose backing binary or service isn't running are especially wasteful — they take space but can't succeed. Anthropic's own [cost guide](https://code.claude.com/docs/en/costs) also points out that CLIs such as `gh` or `aws` add no per-tool listing at all, so they stay cheaper than the equivalent MCP server.

### Manage CLAUDE.md carefully

`CLAUDE.md` is re-read at the start of every session and can be injected into the context on each turn depending on your setup. A long, unstable `CLAUDE.md` is doubly costly: it consumes tokens *and* it defeats [prompt caching](https://tokenade.net/en/glossary/prompt-caching), because cache hits require the prefix to be identical across turns.

Keep `CLAUDE.md` to durable project conventions — build commands, code style rules, architecture decisions that don't change week to week. Strip transient notes, in-progress task lists and anything session-specific. A tight, stable `CLAUDE.md` stays cache-friendly and re-charges the cache on every session after the first.

### Use `/compact` and session hygiene

Claude Code's `/compact` command compresses the conversation history, replacing earlier turns with a summary. It's most effective when you run it between distinct subtasks rather than letting the full transcript accumulate indefinitely.

Good session hygiene for Claude Code:
- **Start a new session for unrelated tasks.** Continuing a long session into a new task carries all prior context even when it's irrelevant.
- **Run `/compact` at natural breakpoints** — after a feature is done, after a debugging session wraps up, before starting a refactor.
- **Don't paste large files or long logs into the chat directly.** Claude Code has file tools; use them selectively rather than front-loading context.
- **Prefer narrow task descriptions.** "Fix the failing test in `auth/login.test.ts`" produces far tighter retrieval than "improve the auth system" — and tighter retrieval means a shorter loop.

## How to apply this today

1. **Stop opening whole files.** Direct Claude Code to the function or symbol you need, not the file that contains it.
2. **Add terse flags** to the commands Claude Code runs most: `--porcelain`, `--quiet`, `--silent`, `2>&1 | grep error`.
3. **Audit your MCP servers.** Disable any you haven't used this week; re-enable when needed.
4. **Trim `CLAUDE.md`** to rules that won't change for months. Delete transient notes.
5. **Run `/compact` between subtasks**, not just when the context warning appears.
6. **Start fresh sessions** for tasks unrelated to what you just worked on.

If wiring all of this up manually sounds like a second job, [Tokenade](https://tokenade.net/en) closes the gap: it applies semantic retrieval, output compression, structure-first reads and lazy MCP loading automatically inside Claude Code, with zero per-prompt configuration. On the open THOL benchmark, the stacked effect cuts what a session costs by 39% on long sessions against running no tool at all.

## What goes wrong (anti-patterns)

**"Read the whole project first."** This feels like thoroughness; it's actually a token grenade. Claude Code front-loads tens of thousands of tokens it will largely ignore, and pays for each of them again on every subsequent turn.

**Leaving raw logs in the chat.** Pasting a failed build verbatim — or letting Claude Code dump it unfiltered — can cost more tokens than the fix. Filter first, then let Claude Code see the error line.

**Treating output optimisation as the fix.** Asking Claude Code to "be brief" trims its *output* (the cheap part). On Claude's pricing, output tokens cost 5× input tokens across the current line-up (Sonnet 5.5 is $2 in / $10 out per million, Opus 5.5 $4 / $20, as of October 2026), but output *volume* is small — it's the input you keep feeding in that dominates. The expensive direction is input.

**One endless session for everything.** Unbounded conversation history re-bills every early read on every new turn. Compacting or restarting between tasks is not a workaround — it's correct session management.

**Ignoring the MCP manifest.** Adding MCP servers is easy; the cost of each one accumulates invisibly. Every tool definition is paid for on every turn whether or not you need it.

## Frequently asked questions

### Does cutting tokens make Claude Code's answers worse?

No — when done correctly, it makes them better. The levers described here remove low-value context: boilerplate command output, irrelevant file content, unused tool definitions. They don't remove the signal Claude Code reasons over. Because models attend least to information buried in a bloated [context window](https://tokenade.net/en/glossary/context-window), removing noise raises the signal-to-noise ratio. The only way to hurt quality is to compress away something load-bearing — which is why structure-first reads keep every function signature, and output filters keep the actual error.

### What does `/compact` actually do?

`/compact` replaces the earlier turns in Claude Code's conversation history with a compressed summary, so the context window is reclaimed. It preserves task-relevant facts (what was built, what errors were seen, decisions made) and drops the verbatim tool outputs and file reads that generated them. Running it proactively between subtasks — rather than only when the context warning fires — means you start each subtask with a leaner, cheaper baseline. You can also steer the summary: `/compact Focus on code samples and API usage` tells Claude what to preserve ([Claude Code cost docs](https://code.claude.com/docs/en/costs)). The [/compact guide](https://tokenade.net/en/articles/claude-code-compact) covers when it fires and what it costs.

### How much should I expect to save?

It depends on your session mix. Sessions heavy on file navigation and build/test cycles — the common pattern for greenfield features or debugging — have the most to gain, because those are the token-heavy activities. Sessions that are mostly the model writing new code from a clear spec have less headroom, since output is already the irreducible part. The honest approach: measure your baseline with a usage counter, apply the levers that match your bottleneck, then compare.

### Does CLAUDE.md affect prompt caching?

Yes, directly. Prompt caching on Claude requires the prefix to be identical across turns to get a cache hit, priced at 10% of a fresh input token on Sonnet 5.5 and Haiku 4.5, 5% on Opus 5.5 and 2.5% on Fable 5.1 ([Anthropic pricing](https://platform.claude.com/docs/en/about-claude/pricing), as of October 2026). A `CLAUDE.md` that changes frequently — because it contains in-progress notes or task-specific reminders — defeats the cache and gets re-billed at full price every session. Keeping it stable and concise is both a direct token reduction and a cache-hit multiplier. See [prompt caching](https://tokenade.net/en/glossary/prompt-caching) for the mechanics.

### Do these techniques work with tools like Cursor or Windsurf too?

Yes. The mechanics are agent-agnostic — every token-billed agent that re-reads its transcript each turn benefits from the same levers. The [broader guide](https://tokenade.net/en/articles/reduce-ai-coding-agent-token-usage) covers the cross-agent picture, and [context engineering](https://tokenade.net/en/articles/context-engineering) goes deeper on the discipline behind these patterns.

---

**See also:**
- [How to reduce AI coding agent token usage](https://tokenade.net/en/articles/reduce-ai-coding-agent-token-usage) — the cross-agent pillar this article branches from.
- [Context engineering for AI coding agents](https://tokenade.net/en/articles/context-engineering) — the discipline behind every lever above.
- [Best MCP servers for Claude Code](https://tokenade.net/en/articles/best-mcp-servers-for-claude-code) — which MCP tools are worth keeping loaded.
- [Claude Code skills](https://tokenade.net/en/articles/claude-code-skills) — what they add to a session, and what they cost it.
- [Best Claude Code token optimizers](https://tokenade.net/en/articles/best-claude-code-token-optimizers) — a comparison of tooling options.
- [AI coding agent token costs](https://tokenade.net/en/stats/ai-coding-agent-token-costs) — the pricing numbers behind the math.