How to reduce Claude Code costs: a checklist from the official docs

How do you reduce Claude Code costs?

You reduce Claude Code costs by sending fewer tokens: clear context between tasks, use Sonnet and a lower effort level for routine work, keep the prompt cache warm, and move verbose work out of your main conversation. Anthropic's costs page frames the whole topic in one line: "Token costs scale with context size: the more context Claude processes, the more tokens you use."

This page is a checklist of the documented ways to do that. If you first want to understand what you are paying and how to read the numbers, start with the Claude Code cost guide.

1. What should you check before changing anything?

Run /usage. On a Pro, Max, Team or Enterprise plan it shows a breakdown of what counts against your limits: usage attributed to skills, subagents, plugins and individual MCP servers, plus recommendations for any behavior behind at least 10% of your recent usage. A row might read 25% Trim ~/code/api/CLAUDE.md · 49k tokens per request. Press d or w to switch between the last 24 hours and 7 days.

The percentage is how much usage the row applies to, not how much the change saves. On v2.1.305 or later, when the footer shows a hint such as f to fix 2 of 3, pressing f runs the suggested /effort commands and asks Claude to apply the other changes it can, showing you each one first.

With an API account, the Session block in /usage shows an estimated dollar cost and a Prompt cache (main) line with your cache hit rate and misses. For a report on how you work rather than what you spent, run /insights.

2. Why is /clear the cheapest habit?

Claude Code sends your full conversation with every request. The docs warn that "Stale context wastes tokens on every subsequent message," so a quick question in a session that has been open all day still pays for the whole history.

When you switch to unrelated work:

1. Run /rename so you can find the session later.
2. Run /clear to start fresh.
3. Use /resume if you need the old session back.

The costs page says unexpectedly high spend on an API or cloud-provider plan "usually traces back to long sessions that were never cleared or to Opus left as the default model."

3. Which model should you use to save money?

The docs are direct: "Sonnet handles most coding tasks well and costs less than Opus. Reserve Opus for complex architectural decisions or multi-step reasoning." Switch with /model or set a default in /config.

Two details matter. Switching to Opus also switches the subagents that inherit your session's model. And for simple subagent tasks, set model: haiku in the subagent's definition. The models guide covers aliases and defaults.

4. How much does effort affect cost?

A lot, on reasoning-heavy work. The docs explain that "Thinking tokens are billed as output tokens, and the default budget can be tens of thousands of tokens per request depending on the model." For simple tasks, lower the level with /effort or in the /model picker.

On models that allow it, you can turn thinking off in /config; Opus 5.5, Sonnet 5.5, Haiku 5.5 and the Fable models always think. On models with a fixed thinking budget, MAX_THINKING_TOKENS=8000 lowers the budget, while adaptive-reasoning models ignore it. The effort guide explains each level and its defaults.

5. How do you avoid paying for cache misses?

Prompt caching makes repeated context cheap, and some actions can throw it away. The prompt caching docs list them, including switching models, changing effort on most models, turning fast mode on, connecting or removing an MCP server, enabling or disabling a plugin, and compacting.

Ways to keep the cache working for you:

• Pick your model and effort at the start of a task rather than switching midway. Each model has its own cache.
• Mind breaks. Your first message after a break longer than the cache lifetime reprocesses everything. On a Claude subscription within plan usage, the main conversation gets a one-hour cache by default; with an API key, usage credits or a cloud provider it gets five minutes.
• Choose the TTL yourself. The promptCacheTtl setting takes 5m or 1h. API users who often step away can set 1h, which costs more per cache write but skips the rebuild. For short bursts that never idle past five minutes, the shorter TTL is cheaper.
• Rewind instead of compacting when you want to abandon a path. /rewind returns to a prefix that is already cached.

The prompt caching guide goes deeper.

6. When should you compact?

Auto-compaction summarizes the conversation as it nears the context limit, but compaction is not free. The docs note that /compact "reads the conversation it summarizes, so compacting a large context is itself a large request." It is cheapest while the cache is warm and most expensive on an old session you just resumed.

So compact at a natural break between tasks, not mid-task, and tell it what to keep: /compact Focus on code samples and API usage. You can also add a # Compact instructions section to CLAUDE.md. If you don't need continuity, /clear costs nothing. More in the compact guide.

7. How do you shrink what loads every session?

CLAUDE.md is loaded at the start of every session, so detailed workflow instructions in it cost tokens even during unrelated work. The docs recommend moving those into skills, which "load on-demand only when invoked," and to "Aim to keep CLAUDE.md under 200 lines by including only essentials."

A skill can also save exploration. A "codebase-overview" skill that describes your architecture and naming conventions gives Claude that context at once, instead of reading many files to work it out.

8. How do you cut MCP overhead?

MCP tool definitions are deferred by default, so only tool names and server instructions enter context until Claude uses a tool. Still, the docs give two tips:

• Prefer CLI tools such as gh, aws, gcloud and sentry-cli, which "are still more context-efficient than MCP servers because they don't add any per-tool listing."
• Disable servers you aren't using in /mcp.

Run /context to see what fills the window. For typed languages, a code intelligence plugin lets Claude jump to a definition instead of grepping and reading several candidate files.

9. How can hooks cut tokens?

A hook can preprocess data before Claude sees it. The docs give the example of a 10,000-line log: instead of Claude reading all of it, a hook greps for ERROR and returns only matching lines, "reducing context from tens of thousands of tokens to hundreds."

The costs page includes a ready PreToolUse hook that rewrites npm test, pytest and go test commands to show only failures. Check it with /hooks after adding it.

10. Do subagents save money?

They save main-context tokens. Running tests, fetching docs or processing logs in a subagent keeps the verbose output in the subagent's context, and only a summary returns.

The subagent's own requests still count, so keep them cheap. Give a subagent a smaller model in its definition, or run every subagent on one model with CLAUDE_CODE_SUBAGENT_MODEL plus CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1. Note that subagents get a five-minute cache even on a subscription unless you set subagentPromptCacheTtl.

11. What about agent teams?

Agent teams run several Claude Code instances, each with its own context. The docs say they use "approximately 7x more tokens than standard sessions when teammates run in plan mode." To keep that in check, use Sonnet for teammates, keep teams small, keep spawn prompts focused, and shut teammates down when their work is done.

12. Which working habits waste the fewest tokens?

The last group of tips is about not doing work twice:

• Be specific. "Add input validation to the login function in auth.ts" needs far fewer file reads than "improve this codebase."
• Plan first. Press Shift+Tab to reach plan mode for complex tasks, so a wrong direction is caught before code is written.
• Stop early. Press Escape when Claude heads the wrong way, and use /rewind to restore a checkpoint.
• Give verification targets such as tests or expected output, and test one file at a time.

Also watch idle sessions. Background summarization costs little, typically under $0.04 per session per the docs, but scheduled tasks, goal check-ins and cross-session messages each send your full context when they fire.

How do teams cap spend?

For organizations, the controls depend on setup: spend limits in admin settings on Team and Enterprise, workspace spend limits in the Claude Console, and your cloud's budget tools on Bedrock, Agent Platform or Foundry. Admins can cap effort with maxEffortLevel, and claude -p runs accept --max-budget-usd. If you are hitting plan limits rather than a bill, see the rate limits guide.

Reuse prompts instead of rewriting them

A vague prompt typed from memory is one of the quiet costs on this list. Kipt keeps your prompts and Agent Skills as Markdown in a private GitHub repo you own, with {{name:default}} blanks you fill in and Cmd+K search, so the specific version of a prompt is the one you reach for.