Reduce Claude Code Token Usage

To reduce Claude Code token usage, control what the model has to process on every turn. A short answer can still be expensive when the request carries a long conversation, several file reads, command output, project instructions, tool definitions, and extended thinking behind it.

The useful target is not the fewest tokens in one response. It is the lowest total cost for an accepted change: research, edits, tests, corrections, and human review included.

This guide uses current Claude Code controls such as /usage, /context, /clear, /compact, /model, /effort, and /mcp. It applies most directly to API-billed sessions. Subscription plans use allowance windows rather than a per-request invoice, but the same context habits can help an allowance last longer.

Why Claude Code uses more tokens than a chat answer

Claude Code is an agent, not a single prompt followed by a single response. A working session can include:

• your prompt and every relevant earlier turn;
• files Claude reads while exploring the repository;
• command, test, compiler, and tool output;
• CLAUDE.md, applicable project rules, and invoked skills;
• tool definitions and results from MCP servers;
• planning, extended thinking, generated code, and explanations;
• subagent summaries and any follow-up corrections.

Context is cumulative. When a stale log or an unrelated design discussion remains in the conversation, later turns may process it again. Prompt caching can reduce the price of repeated content, and Claude Code automatically compacts history near its context limit, but neither is a reason to keep irrelevant material forever.

That leads to a practical order of operations:

1. measure one representative task;
2. remove unrelated context;
3. reduce standing instructions and tool overhead;
4. prevent broad exploration and noisy output;
5. choose model and effort deliberately;
6. measure the completed task again.

Start with a baseline, not a feeling

Run /usage before optimizing. For API users, its Session block reports token usage by model and a local cost estimate at standard list rates. That estimate may not include a gateway promotion or contracted rate, so use the provider's bill as the financial source of truth.

Run /context to see what is occupying the current context window. This is where a large CLAUDE.md, an invoked skill, or tool overhead becomes visible instead of remaining a guess.

If the session uses OmniaKey, compare those local diagnostics with the usage dashboard. It records the requested model, input and output tokens, cache metadata, latency, and actual per-call cost. The balance and usage guide explains account balance, key caps, and usage records.

Choose one repeatable task for the before-and-after check. Record:

Do not compare two unrelated sessions. A typo fix and an unfamiliar migration do not provide a useful token benchmark.

1. Clear between unrelated tasks

The highest-value habit is also the simplest: use /clear when the next task does not need the current conversation.

Before clearing a session you may need later, give it a name:

/rename auth-refresh-investigation
/clear

The earlier session remains available through /resume. Current Claude Code also resets the Session totals shown by /usage after /clear, which makes the next task easier to measure separately.

Good reasons to clear include:

• moving from a backend bug to unrelated marketing copy;
• finishing a feature and starting a new repository area;
• abandoning an approach whose assumptions were wrong;
• carrying several large logs that no longer affect the decision.

Do not clear merely because the context meter moved. If the task is still active, preserve the verified facts and decisions first, or compact the conversation with explicit instructions.

2. Compact deliberately during long work

/compact summarizes older history so later turns can work from a smaller representation. Add an instruction that names what must survive:

/compact Preserve the acceptance criteria, changed files, failing test output, and unresolved decisions.

That is safer than a generic summary for a long implementation. You can also place short compaction guidance in CLAUDE.md when the same preservation rule applies across the project.

Compaction is not the same as a subscription usage reset, and a context warning is not a billing-limit warning. Compaction manages what remains in the conversation. It does not add plan allowance or top up an API balance.

Use it when the task is still coherent but the path to the current state was noisy. Use /clear when the work itself has changed.

3. Shrink the context that loads before work starts

Claude Code reads project instructions at session start. Useful instructions prevent mistakes; a handbook copied into every session consumes context whether the task needs it or not.

Anthropic's current guidance recommends keeping CLAUDE.md concise and moving specialized workflows into skills that load on demand. A good root file contains:

• commands that verify a change;
• repository-specific architecture boundaries;
• non-obvious environment constraints;
• conventions that differ from normal language defaults.

Move long API tutorials, one-off migration runbooks, and domain reference material elsewhere. Link to them or package them as a focused skill instead of embedding them in every session.

MCP servers create a similar tradeoff. Run /mcp and disable servers you are not using. Claude Code defers full tool definitions by default, but names and invoked schemas still occupy context. For a simple operation, a focused CLI such as gh, aws, or sentry-cli can be more context-efficient than loading a broad tool surface.

Check /context again after pruning. If the starting footprint did not change, find the actual large contributor before editing more configuration.

4. Make the task narrow enough to avoid discovery loops

"Improve this repository" invites scanning. A bounded prompt can go directly to evidence:

Fix the 401 after token refresh in src/api/auth.ts.
Preserve the public response shape.
Add a regression test for an expired access token with a valid refresh token.
Run the focused auth test and the type checker.

The prompt identifies the symptom, likely file, contract, and proof. Claude can still inspect dependencies when needed, but it has a reason not to read the whole codebase.

For genuinely complex work, plan before editing. A short research and plan phase can prevent an expensive implementation on the wrong architecture. For a one-line, well-located fix, planning can be overhead. Use it when uncertainty is real.

Course-correct early. If Claude is solving the wrong problem, stop the turn rather than letting it generate a large patch and then explaining why the patch must be undone. /rewind can restore a prior conversation and code checkpoint.

An output contract also helps:

• lead with the decision;
• list only changed files and verification results;
• do not repeat the prompt;
• ask for missing information before implementation;
• cap an artifact only when truncation will not hide required evidence.

Shorter prose saves some output tokens. Avoided exploration and rework usually save more.

5. Keep tool and test output focused

Large command output enters the working context. Prefer the narrowest command that can prove the change:

pnpm vitest run tests/unit/auth.test.ts
rg -n "FAIL|ERROR" test-output.log
git diff --check

Do not hide failures just to reduce tokens. Keep the failing assertion, relevant stack frames, command exit status, and enough surrounding output to diagnose the cause. Drop repeated progress bars, successful test lists, and thousands of unrelated log lines.

Stable preprocessing belongs in a script or hook. Anthropic's cost guide gives the example of filtering a very large test log before Claude sees it. A small, reviewed filter is more reliable than asking the model to rediscover the same noise pattern on every run.

For research that requires many file reads, a bounded subagent can keep verbose exploration out of the main conversation and return a short result. This isolates context; it does not guarantee fewer total tokens, because the subagent has its own context. Use it when the summary will prevent repeated reading in the main task.

6. Match model and effort to the decision

Model choice changes both rate and the number of attempts needed. Claude Sonnet 5 is a practical daily starting point, Claude Haiku 4.5 fits narrow repeatable work, and Claude Opus 5 is easier to justify when architecture, ambiguity, or the cost of an error is high.

Use /model to switch intentionally. The Claude Code model guide gives a fuller task-routing policy.

Extended thinking tokens are billed as output tokens on API paths. For a simple, well-specified task, lower effort with /effort and measure whether the result still passes. For hard planning or unfamiliar debugging, too little effort can create retries that erase the saving.

Do not route every task to the cheapest model and call the policy optimized. Compare cost per accepted result, including corrections and review debt.

7. Add a financial guardrail after reducing usage

A spending cap does not reduce token consumption. It limits the financial damage if a loop, leaked key, or unexpected workload keeps sending requests.

With OmniaKey, create separate keys for local development, automation, and shared workloads in the API Keys dashboard. Give each key a cap that matches its job, then review usage before raising it. Separate keys make attribution and revocation clearer than one unlimited credential everywhere.

The sequence matters:

1. remove unnecessary context and retries;
2. measure the normal task cost;
3. set a cap above legitimate variance;
4. alert or stop when the workload crosses that boundary.

A cap that is too low merely turns a cost problem into a mid-task failure. A cap with no usage review tells you only that the ceiling was reached.

A 10-minute Claude Code token audit

Use this checklist on one real session:

1. Run /usage and record usage by model.
2. Run /context and identify the largest avoidable contributor.
3. Use /clear if the current task is unrelated to the earlier conversation.
4. Shorten CLAUDE.md; move specialized instructions to on-demand skills.
5. Disable unused MCP servers with /mcp.
6. Replace broad prompts with a file, symptom, boundary, and acceptance check.
7. Run focused tests and filter repetitive output without hiding failures.
8. Use /model and /effort according to task difficulty.
9. Repeat the same task class and compare completed-task cost.
10. Add a per-key cap after you know the normal range.

Change one or two variables at a time. If you clear the session, change the model, lower effort, and rewrite the task simultaneously, you will not know which change helped.

Common mistakes

Asking only for shorter answers

This reduces visible output but leaves file reads, history, tools, and thinking untouched. It is useful, just rarely the largest lever.

Deleting context the task still needs

Missing constraints cause guessing and rework. Preserve verified decisions before clearing or compacting.

Treating cache hits as zero usage

Prompt caching can lower the price of repeated input, but cached tokens still appear in usage accounting. Keep repeated context useful and check the actual billing record.

Using a subagent for every small question

Each subagent has its own startup and working context. Delegate bounded, high-volume exploration; answer a tiny local question in the current session.

Confusing a cap with optimization

A key cap stops spend at a boundary. It does not make the requests below that boundary more efficient.

Frequently asked questions

Why is Claude Code token usage high when the answer is short?

The request can include conversation history, project instructions, files, command output, tools, and thinking that are much larger than the final text. Check /context and /usage rather than judging by answer length.

Does /clear delete my previous Claude Code session?

It starts a fresh session. Rename important work first and use /resume to return to the preserved session later.

Does /compact always reduce my bill?

It reduces the history carried into future turns, which can lower later input usage. The net effect depends on how long the session continues and what the summary preserves, so verify it with /usage and your billing dashboard.

Should I always use Haiku to save tokens?

No. A cheaper model can be economical for narrow work, but repeated failed attempts can cost more than one successful Sonnet or Opus turn. Route by task and measure accepted results.

Can an API key spending cap reduce token usage?

No. It bounds spend after requests consume usage. Combine caps with smaller context, focused prompts, deliberate model effort, and per-call review.

Sources

• Anthropic: manage Claude Code costs
• Anthropic: explore the Claude Code context window
• Anthropic: Claude Code best practices
• Anthropic: configure Claude Code models and effort
• Anthropic: prompt caching
• OmniaKey balance and usage documentation

Fact-checked August 8, 2026. Claude Code commands, model behavior, and billing surfaces change; verify the linked first-party documentation and your actual usage records before setting a production budget.