The Token-Efficient Claude Code Playbook

Summary

Claude Code bills for tokens, and the single biggest driver of token spend is how much context rides along on every message, not the model you pick. The API is stateless: each turn re-sends the entire conversation so far. By turn 30, you are paying to re-read turns 1 through 29. That is why a focused, deliberately-managed session outperforms a long rambling one on both quality and cost.

This playbook covers the mechanisms that matter, in priority order: keep sessions short and clear between tasks; let cheaper models and subagents do the cheap work; keep prompt caching warm; connect only the MCP servers you need and let the newer deferred-loading default do the rest; and keep your CLAUDE.md and knowledge base lean so they earn their place in every message. Each section ends with something you can copy and use today.

Business Impact

• The same work costs less. Anthropic's own teams report roughly $13 per developer per active day; the habits below are what keep an individual near that figure instead of several multiples of it.
• The answers get better as the bill drops. Every efficiency move here (clearing stale context, routing the right model, keeping the knowledge base lean) also improves the output, because a cluttered context window degrades Claude's performance well before it fills.
• The savings compound across a team. One person's tidy CLAUDE.md, scoped MCP config, and session discipline become the template everyone copies, so the whole org drifts toward the efficient default.

The one idea to hold onto

Anthropic states it plainly in the official best-practices guide: "the context window is the most important resource to manage." Performance degrades as context fills, and because every message re-sends the full history, token spend is a direct function of how well you manage that window.

Simon Willison puts the cost side memorably: a 4,000-token CLAUDE.md is not a one-time cost, it is "a 4,000-token tax on every message." Most of what you pay for in a long session is the agent re-reading its own past. Every technique in this guide is a way of paying that tax less often, or in a smaller amount.

Three numbers frame everything that follows:

Hold that frame and the rest of this guide is tactics. The community heuristics you will hear ("the 40% rule," "one task per session," spec-driven fresh sessions) are all downstream of that single Anthropic constraint.

Where your tokens actually go

Before optimizing, see the bill. Claude Code gives you the instruments; use them before you guess.

Command	What it shows you
/context	The context-window breakdown right now: system prompt, CLAUDE.md, memory, MCP tool definitions, and conversation, each as a token count and a share of the window. This is your primary audit tool.
/usage	Session token and cost stats. On paid plans it attributes recent usage to skills, subagents, plugins, and individual MCP servers, and flags anything (a long context, repeated cache misses) that accounts for a large share of spend.
statusline	A live context-usage readout in the terminal, so you notice the window filling before it forces a compaction.

The four line items that dominate most bills:

• Re-sent conversation history. The stateless-API tax. Grows every turn; the only cure is clearing or compacting.
• File reads. Each read drops the whole file into context. Being specific ("fix the bug in auth.ts") reads far less than "improve the codebase," which sends Claude searching and reading widely.
• MCP tool definitions. Historically the quiet killer; now largely defused by default (see the MCP Fleet section). Still worth auditing.
• Extended thinking. Thinking tokens bill as output, and default budgets can run to tens of thousands of tokens per request. Great for hard problems, wasteful on rote ones.

The context playbook (highest leverage)

Everything here keeps the conversation layer small and relevant, which is where the largest savings live.

/clear liberally between unrelated tasks

Anthropic names the top failure mode "the kitchen sink session," and the fix is one command: /clear between unrelated tasks. Stale context wastes tokens on every subsequent message and quietly degrades answers, because history from one task contaminates the next. /clear is free; it erases rather than processing. Reach for it the moment you switch problems.

After two failed corrections, clear and re-prompt

A hard rule from the best-practices guide: if you have corrected Claude more than twice on the same issue in one session, stop correcting. Run /clear and start fresh with a better prompt. A clean session with a sharper prompt almost always beats a long session carrying accumulated corrections, and it is cheaper.

/compact at task boundaries, not mid-thought

Where /clear wipes everything, /compact replaces the conversation history with a structured summary while preserving your system prompt, CLAUDE.md, and memory. Use it when you want to free space but keep continuity. Give it focus so the summary keeps what matters:

/compact Focus on the API changes and the exact list of files modified so far.

You can also encode a compaction rule in CLAUDE.md once (for example, "when compacting, always preserve the full list of modified files and any test commands") so every compaction keeps your load-bearing details.

	/clear	/compact
Keeps	System prompt, CLAUDE.md, memory (fresh from disk)	Those plus a summary of the conversation
Loses	The entire conversation	The verbatim conversation (replaced by summary)
Use when	Switching to an unrelated task	Continuing the same task but low on room
Cost	Free; erases	One pass to summarize the conversation, then a fresh cache

Plan before you spend, but skip it for one-liners

Plan mode (Shift+Tab) lets Claude explore and propose an approach before it edits, which prevents the expensive rework of coding down the wrong path. Anthropic's rule of thumb is exact: "If you could describe the diff in one sentence, skip the plan." Use plan mode for multi-file changes and unfamiliar code; skip it for a bug fix or a formatting tweak, where the plan itself is just overhead.

Give the files up front; do not let it grep blindly

"The infinite exploration" is a named waste pattern: an under-scoped request sends Claude reading file after file. Head it off by pointing at sources with @file references and naming the pattern to follow ("HotDogWidget.php is a good example"). One precise instruction reads a fraction of what open-ended investigation does.

Batch related questions into one message

Because every message reprocesses the whole history, three separate follow-ups cost three full re-reads. Ask the three related things in one message and pay for the history once.

Model routing: match the model to the job

Anthropic names "Opus left as the default model" as a top cause of surprise bills. The guidance is 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, and set a cheaper model on simple subagents.

Model	ID	In / Out per M	Context	Reach for it when
Opus 5	claude-opus-5	$5 / $25	1M	Hard reasoning, architecture, multi-step debugging, long-horizon agentic work
Sonnet 5	claude-sonnet-5	$3 / $15	1M	The default for most coding and analysis; near-Opus quality at lower cost
Haiku 4.5	claude-haiku-4-5	$1 / $5	200K	Simple, speed-critical work: exploration subagents, mechanical edits, classification

Pricing per million tokens, from Anthropic's current model reference (Sonnet 5 has an introductory $2 / $10 rate through August 31, 2026). Confirm live figures on Anthropic's pricing page before quoting dollars in a stakeholder doc.

Effort is a token dial, not just a quality dial

Reasoning effort (/effort, or per-subagent) controls how much the model thinks, and thinking bills as output. Use low for rote work and exploration, the default for most tasks, and raise it only for genuinely hard reasoning. Lowering effort on a simple task is one of the cleanest savings available.

Prompt caching: keep it warm, do not break it

Claude Code caches automatically. You never manage it directly, but you can absolutely break it, and a broken cache means re-paying full price for context you already sent. The rule is a prefix match: the API reuses the unchanged start of your request at roughly a tenth of the input price and only fully processes what is new at the end.

What invalidates the cache (a full, full-price re-read)

• Switching model, effort level, or fast mode mid-session.
• Editing anything early in the prefix: the system prompt, or in your own scripts, a timestamp or UUID near the front.
• Connecting or disconnecting an MCP server whose tools are loaded into the prefix (deferred tools do not trigger this).
• A Claude Code upgrade, which typically changes the system prompt.

What keeps it warm

• Editing files in the repo (appends a change notice; does not touch the prefix).
• Running /compact at a boundary (rebuilds the cache once, then rides it).
• Staying on one model and one effort level for the whole session.

Setting up your MCP fleet so it costs nothing at rest

MCP setup is where most token waste used to hide, so it gets the most detail here. Every connected MCP server's tool definitions, the names, descriptions, and full input schemas, historically loaded into context at session start, before you typed a word. Anthropic measured a typical five-server setup (GitHub, Slack, Sentry, Grafana, Splunk) at about 55,000 tokens of definitions up front, with larger real-world fleets hitting 134,000 tokens before any work began.

The engineer's checklist, in priority order

1. Only connect servers you actually need, and scope them per project. This is the biggest lever after the deferred-loading default. Put narrow, project-specific servers in a project-scoped .mcp.json so they load only where relevant; reserve user scope for the one or two servers you genuinely use everywhere. Do not dump everything into user scope.
2. Disable unused servers with /mcp. Run /mcp to list connected servers and turn off any you are not using this session. Tools like McPick (npx mcpick) make this a pre-session toggle.
3. Prefer a CLI when one exists. Anthropic's own guidance: gh, aws, gcloud, and similar are more context-efficient than an MCP server because they add no per-tool listing at all. Claude just runs the command, and you can pipe the output through jq, grep, or head so intermediate JSON never enters the context window. Reach for an MCP only when the service has no usable CLI.
4. Audit with /context and /usage. See exactly what your fleet costs and which server is the offender, then act. Remember the per-server over-counting caveat.
5. If you build your own MCP, trim it. Consolidate near-duplicate tools behind one parameter, cut verbose descriptions, and namespace tool names by service (github_, slack_) so one search matches a whole group. One documented refactor took a server from 20 tools and ~14,000 tokens to 8 tools and ~5,600 tokens, a 60% cut.

Scoping MCPs correctly with the API

The scope you choose decides where a server loads and who shares it. Three levels, precedence local > project > user:

# Project scope: shared with the team via a committed .mcp.json at the repo root.
# Loads only in this project. Best for narrow, project-specific servers.
claude mcp add --scope project my-server -- 

# User scope: available across all your projects. Reserve for the 1-2 servers
# you truly use everywhere. Do not put project-specific servers here.
claude mcp add --scope user shared-server -- 

# Local scope: this project, private to you (not committed). Good for experiments.
claude mcp add --scope local scratch-server --

A committed project .mcp.json is prompted for approval on first use and shows as "pending" in claude mcp list until you approve it, which is the intended safety gate for team-shared servers.

Connect via API the efficient way: prefer remote/HTTP over heavy local processes

Transport choice does not change the token cost of a tool definition, but it changes reliability and overhead. A stdio server spawns a local process per server (its own runtime, dependencies, startup cost, and local failure modes). A remote HTTP or SSE server is hosted and OAuth-authed, with no local process to manage. So choose transport for reliability and authentication, and control tokens with the checklist above. When you aggregate many remote servers, set deferred loading once at the toolset level so the aggregate never blows up the context window.

Agents: the most powerful context tool you have

Subagents run in their own separate context windows and return only a summary to your main thread. Anthropic's own framing: because context is the fundamental constraint, subagents are one of the strongest levers available. Simon Willison calls the pattern "context quarantine": the exploration happens somewhere else, and your main window never sees the mess.

One documented example makes the whole case. A subagent reads about 6,100 tokens of files and returns a roughly 420-token result. The 5,700 tokens it read never touch your main window. Do that a few times a session and you have kept the main thread lean enough to stay in the sharp zone.

When a subagent pays for itself

• Research and exploration. "Find where X is configured and how it flows" is a read-heavy question whose answer is small. Delegate it; keep the summary.
• Parallel independent work. Several unrelated audits or refactors can each run in their own context and merge back, rather than serializing in one window.
• Verification by a fresh model. A separate agent grading the diff catches what the writer, biased toward its own work, misses. Fresh context improves review.

Route agents by cost, too

An exploration subagent does not need Opus. Give research and mechanical agents Haiku at low effort; save Opus and high effort for the architect. A subagent warms its own cache from its second turn but uses a five-minute cache TTL even on a subscription, so keep each one focused and short.

Optimizing your knowledge base: CLAUDE.md, skills, and hooks

Your CLAUDE.md loads into every message. That is the whole reason to keep it lean: it is the clearest example of Willison's per-message tax, and a bloated one also causes Claude to ignore your actual instructions. Anthropic's number is explicit and repeated across its docs: keep CLAUDE.md under 200 lines, give it an owner, and review changes to it like code.

The one test for every line

For each line in your CLAUDE.md, ask: would removing this cause Claude to make a mistake? If not, cut it. That single question keeps the file honest.

Belongs in CLAUDE.md	Does NOT belong
Bash commands Claude can't guess	Anything it can learn by reading the code
Non-default code-style rules	Standard language conventions
Test runner and how to run tests	Detailed API docs (link instead)
Branch and PR etiquette	Frequently-changing information
Project-specific gotchas and decisions	File-by-file descriptions of the repo

Move "sometimes" knowledge out of the always-loaded file

• Skills load on demand, not on every message. A deploy checklist, a release process, a review playbook, a repeatable workflow: put it in a skill, and it costs nothing until it is relevant. This is the single best way to shrink a CLAUDE.md without losing capability.
• Path-scoped rules (.claude/rules/ with a paths: frontmatter) load only when Claude touches matching files. API guidelines that apply only under src/api/** should live here, not in the always-on file.
• Slash commands turn a prompt you retype into one you invoke (/fix-issue 1234), so the phrasing is written once and reused.
• Hooks are deterministic, not advisory. A PostToolUse hook can grep a 10,000-line log down to the few hundred tokens that matter before Claude ever sees the output, turning tens of thousands of tokens into hundreds.
• @import references pull in a file only where you cite it (@docs/git-instructions.md), instead of pasting its contents into the base file.

Copy-paste session recipes

The habits above, assembled into three flows you can run as-is.

The clean single-task session

1. Start the session and pick your model and effort now (Sonnet, default effort, for most work). Do not switch later.
2. Give Claude the files up front with @file and one specific instruction. Skip plan mode if the change is a one-liner; enter it (Shift+Tab) if it spans files.
3. Work the task. If you correct the same thing twice, stop: /clear and re-prompt.
4. Give Claude a way to verify (a test, a build, a screenshot). Let it self-check.
5. Finished? /clear before the next unrelated task.

Spec-driven, fresh-session execution

1. In one session, let Claude interview you and write a self-contained SPEC.md. Time spent making the spec precise pays off more than time spent watching the build.
2. /clear (or start a new session) and execute against SPEC.md with a clean context.
3. Delegate read-heavy investigation to subagents (Haiku, low effort) so the main window stays lean.
4. Test incrementally: write one file, verify, continue. Catching issues early is cheapest.
5. Review the diff in a fresh session (a writer/reviewer split), so the reviewer is not biased toward code it just wrote.

The efficiency setup pass

1. Run /init to generate a starter CLAUDE.md, then prune it against the one-line test until it is under 200 lines.
2. Move procedures into skills and path-scoped rules; keep only always-true conventions in CLAUDE.md.
3. Run /mcp and disconnect every server this project does not use. Scope the ones it does use into a project .mcp.json.
4. Replace any MCP server that duplicates a CLI (gh, aws, gcloud) with the CLI.
5. Turn on the context statusline and do one /context audit to confirm the baseline is lean before you build.

The money-wasting mistakes to stop making

Mistake	Fix
The kitchen-sink session	/clear between unrelated tasks. Named the #1 waste pattern by Anthropic.
Leaving Opus as the default	Route Sonnet for most work, Haiku for the cheap stuff, Opus only for hard reasoning.
Correcting the same thing over and over	After two strikes, /clear and rewrite the prompt.
An over-stuffed CLAUDE.md	Under 200 lines. Move procedures to skills, path rules, and hooks.
Never clearing a long session	The cache-miss-on-resume tax plus the re-read tax. Clear or compact at boundaries.
The infinite exploration	Scope the request; give files with @file; delegate reads to a subagent.
Switching model/effort mid-session	Pick both at the start; every switch re-reads the whole context.
Connecting every MCP server "just in case"	Scope per project, disable the unused, prefer CLIs. Deferred loading handles the rest.
Many small messages in a long session	Batch related questions into one; each message reprocesses the whole history.
Re-reading a file to verify an edit	Trust the edit tool; use a language server / code-intelligence for navigation instead of re-reading.

The one-screen checklist

Every session

• Pick model + effort at the start. Do not switch mid-session.
• Give files up front with @file; be specific in the ask.
• Plan mode for multi-file or unfamiliar work; skip it for one-liners.
• Delegate read-heavy exploration to subagents (Haiku, low effort).
• Give Claude a check it can run; let it verify itself.
• Two failed corrections → /clear and re-prompt.
• /clear between unrelated tasks; /compact at boundaries within one.
• Batch related questions into one message.

Per project, once

• CLAUDE.md under 200 lines; procedures live in skills, rules, hooks.
• Only needed MCP servers, scoped in a project .mcp.json; unused ones disabled.
• CLI (gh/aws/gcloud) instead of an MCP wherever one exists.
• Leave deferred tool loading on (default); do not force ENABLE_TOOL_SEARCH=false.
• Context statusline on; one /context audit to confirm a lean baseline.

FAQ

What is the single highest-leverage habit?

/clear between unrelated tasks. It is free, it is the most common savings Anthropic sees, and it improves answer quality by removing contaminating context. If you adopt one thing, adopt that.

Does a cheaper model mean worse answers?

Not for most work. Sonnet handles the large majority of coding and analysis at near-Opus quality and lower cost; Haiku is genuinely good for exploration and mechanical edits. The waste is using Opus reflexively for tasks that never needed it. Match the model to the job.

Is my MCP fleet still a big token cost?

On a current build, largely not. Claude Code defers MCP tool definitions by default, so only tool names load until a tool is used. The remaining work is disciplined setup: connect only what you need, scope it per project, disable the unused, and prefer a CLI where one exists. Audit with /context, and remember its per-server numbers can overstate real cost.

Should I use the 1M-token context models to avoid compacting?

Rarely as a first move. A bigger window does not fix the underlying problem, which is that quality degrades and cost rises as context fills, regardless of the ceiling. Managing the window (clearing, subagents, lean knowledge base) beats simply raising the limit and letting it fill.

How do I know if I am actually being efficient?

Instrument it. /context shows what is consuming the window right now; /usage attributes recent spend to skills, subagents, plugins, and individual MCP servers and flags anything eating a large share. If a category surprises you, that is your next optimization.

What about the community rules like "the 40% rule"?

They are useful shorthand for Anthropic's own "performance degrades as context fills." Keep the main session comfortably under half the window, wrap up before it gets crowded, and clear before the next task. Treat the specific percentages and ratios (40%, 70/20/10) as heuristics, not hard numbers.

Where do the numbers in this guide come from?

The token measurements (the ~55K five-server fleet, 134K pre-optimization, the 85% tool-search reduction, the 6,100→420-token subagent, "under 200 lines") are from Anthropic's official Claude Code best-practices, cost-management, tool-search, and advanced-tool-use documentation, plus its "how Anthropic teams use Claude Code" post. The rough 7× cost of multi-agent teams is a community estimate, not an official Anthropic figure. Model IDs and pricing are from Anthropic's current model reference; confirm live figures on the pricing page before quoting dollars externally. Practitioner framing (the per-message tax, context quarantine) is attributed to Simon Willison. Anything phrased as a community heuristic is flagged as such.