How to reduce Claude Code token usage, and what each fix costs you

Why does Claude Code use so many tokens?#

Because the model remembers nothing between requests, Claude Code sends the full context every time: the system prompt, tool definitions, your CLAUDE.md, every earlier message and tool result, and your new message. And it sends a request at every step of its loop, each time it reads a file, runs a command or replies. A one-line question late in a long session still carries everything before it.

Prompt caching softens this. The unchanged start of each request is read from a cache, and on Opus 5.5 a cached token costs $0.20 per million instead of $4. But cheap isn’t free. In one session we measured on 2026-10-08, 940 requests over 8.4 active hours, never cleared, the median request carried 426,571 tokens and the largest 966,324. Cache reads were 99.5% of all input tokens and about 72% of what the session would cost at API list prices.

How do I check token usage in Claude Code?#

Two commands tell you most of what you need. Run them before you change anything, so you know which fix matters for you.

• `/context` draws the current context window as a coloured grid, with a breakdown by category (including memory files, MCP tools and skills) and suggestions for heavy tools and bloated memory. In fullscreen mode, /context all shows the full breakdown.
• `/usage` (also /cost and /stats) shows the session’s tokens by model, an estimated cost at list price, and a prompt cache line with the share of input served from the cache and any misses. On Pro, Max, Team and Enterprise it adds plan usage bars and a breakdown by skill, subagent, plugin and MCP server.
• The status line can show context use all the time: Claude Code passes context_window.used_percentage to your status line script.

The dollar figure in /usage is computed on your machine, so treat it as an estimate. On the API, the Console’s usage page is the real bill.

Should I use /clear or /compact?#

Use /clear when you switch to unrelated work, and /compact when you need to keep going on the same task with less history. Anthropic’s cost docs name clearing between unrelated tasks as one of the two highest-impact habits, because stale context costs tokens on every later message.

• `/clear` starts a new conversation with empty context. It costs nothing. Run /rename first if you want to find the old session again with /resume.
• `/compact` replaces the history with a summary. Add focus instructions, such as /compact Focus on code samples and API usage, to choose what survives. The summary is a request that reads the whole conversation: cheap while the cache is warm, expensive after a break.
• `/rewind` (or Escape twice) goes back to an earlier checkpoint when Claude went down the wrong path. It returns to a prefix that is already cached, so it is cheaper than compacting.

You can also tell compaction what to keep in your project’s CLAUDE.md, as the docs suggest:

# Compact instructions

When you are using compact, please focus on test output and code changes

What does clearing save? Our measured session’s cache reads alone come to $88.02 at Opus 5.5 list prices. If clearing between tasks had held each request to 100,000 tokens, the same 940 requests would have read about $18.80. That’s a rough model, not a measurement, but the direction is clear. Claude Code also compacts automatically as the window fills; on 1M-context models, /autocompact 200k sets a lower threshold, trading smaller requests for more frequent summaries. If you see Prompt is too long, the window filled anyway.

Which model and effort level use the fewest tokens?#

The model sets the price of every token, and the effort level sets how many thinking tokens Claude spends. Anthropic’s docs say Sonnet handles most coding tasks well and costs less than Opus, and suggest reserving Opus for complex architectural decisions or multi-step reasoning. Claude Code’s default on Pro, Max, Team, Enterprise and the API is Opus 5.5.

• Switch with `/model`, for example /model sonnet. Opus 5.5 output costs twice as much as Sonnet 5.5’s. Choose at the start of a session: each model has its own cache, so a mid-session switch re-reads the whole conversation uncached.
• Lower the effort with /effort low or /effort medium for routine edits. Thinking is billed as output. Opus 5.5, Sonnet 5.5 and Haiku 5.5 default to medium, and their thinking can’t be turned off.
• Try `opusplan`, which uses Opus in plan mode and Sonnet for the edits. Each switch between them is a model change, so it starts a fresh cache.

On models with a fixed thinking budget, the MAX_THINKING_TOKENS environment variable caps it; adaptive models ignore it, so use effort there. With an API key or a subscription, changing effort on the 5.5 models keeps the cache; on most other models and on Bedrock or Google Cloud it doesn’t.

Keep CLAUDE.md, MCP servers and skills lean#

Everything that loads at session start rides along on every request until you clear. Trim it once and every step gets cheaper.

• CLAUDE.md under 200 lines. It loads in full. @path imports don’t reduce the cost, since imported files load at launch too. Move instructions for one part of the codebase into .claude/rules/ files with paths: frontmatter, which load only when Claude touches matching files, and move occasional workflows (PR reviews, migrations) into skills, which load only when used. Our CLAUDE.md generator warns past 200 lines.
• Disable MCP servers you aren’t using with /mcp disable <name>. By default only tool names and server instructions load until a tool is used, but that deferral (tool search) switches off when ANTHROPIC_BASE_URL points to a third-party gateway, and then every definition loads up front.
• Prefer command-line tools such as gh, aws or gcloud when they exist: the docs call them more context-efficient than MCP servers because they add no per-tool listing.
• Leave notes for humans in HTML comments. Block-level <!-- --> comments in CLAUDE.md are stripped before Claude sees them.
• Run `/doctor` now and then: its checkup weighs unused skills, MCP servers and plugins against their context cost, and proposes cuts to CLAUDE.md content Claude could work out from the code.

Edits to CLAUDE.md take effect after the next /clear, /compact or restart. To see what a file costs, paste it into the token counter; the context window checker shows how much of a model’s window a document takes before you add it to a session.

Write prompts that don’t trigger broad file reads#

Tool results, mostly file contents and command output, are usually the part of the context that grows fastest. The docs’ example: “improve this codebase” triggers broad scanning, while “add input validation to the login function in auth.ts” lets Claude work with minimal file reads.

• Plan first on big tasks. Press Shift+Tab to reach plan mode, so Claude proposes an approach before reading and editing widely.
• Stop early. Press Escape as soon as Claude heads the wrong way; every wasted step adds to the context.
• Give a target. Tests or expected output let Claude check its own work instead of you asking for fixes.
• Install a code intelligence plugin for typed languages: one “go to definition” call replaces a search plus several file reads.

To keep Claude out of build output or generated files, don’t rely on a .claudeignore file: the permissions docs say it has no effect. Add Read deny rules to .claude/settings.json instead. Claude applies them to its file tools on a best-effort basis, including Grep and Glob:

{
  "permissions": {
    "deny": [
      "Read(./dist/**)",
      "Read(./coverage/**)",
      "Read(./.env)"
    ]
  }
}

Use subagents for noisy work, on a smaller model#

Running tests, fetching documentation or reading logs can flood the main conversation. A subagent does that work in its own context and returns only a summary, so your main context stays small. Ask for it directly, as in the docs’ example (“Use a subagent to run the test suite and report only the failing tests with their error messages”), or define one with a cheaper model:

---
name: test-runner
description: Runs the test suite and reports only failing tests with their errors
tools: Bash, Read, Grep
model: haiku
---

Run the tests, then reply with each failing test and its error message. Nothing else.

The trade-off: a subagent’s requests still count, and it starts with an empty cache of its own. Subagents get a five-minute cache lifetime even on a subscription. Agent teams cost more again: Anthropic says they use about 7x the tokens of a standard session when teammates run in plan mode.

What prompt caching already does for you#

Claude Code turns on prompt caching automatically and orders each request so the parts that rarely change come first: system prompt and tools, then project context, then the conversation. A change early in that order invalidates everything after it, which is why these actions cost one slower, full-price step:

• switching model, or changing effort on most models other than the 5.5 generation
• turning on fast mode, compacting, or upgrading Claude Code
• connecting or removing an MCP server, when tool definitions load up front

The cache also expires when you stop. On a subscription within your plan, the main conversation’s cache lasts an hour; on an API key, a cloud provider or usage credits it lasts five minutes. API users can set promptCacheTtl to 1h, which costs more per cache write and pays off if you often pause for longer than five minutes. Our prompt caching guide explains the pricing.