Takeaway: Claude Code’s fixed overhead is mostly a cached prefix, so a cache miss costs you more than the prefix does. Run /context to see what fills the window, and /usage to see how much of your input came from cache. Then fix what is in your control: a long CLAUDE.md, habits that throw the cache away (switching models, toggling plugins), the cache TTL on API keys, subagent model choice, and raw tool output.

Read time: ~9 minutes. Key facts:

• A July logging-proxy test by Systima measured about 33,000 tokens of Claude Code overhead before the prompt (system prompt plus 27 tool schemas). OpenCode came in at about 7,000. That was Claude Code 2.1.207 on Sonnet 4.5.
• MCP tools are now deferred by default. With tool search on, only tool names and server instructions load at session start. Adding MCP servers costs far less than it did in that measurement.
• On a Claude subscription within plan usage, the main conversation gets a 1-hour cache. Subagents and everything else get 5 minutes. With an API key or a cloud provider, the default is 5 minutes unless you set promptCacheTtl.
• Switching models, toggling plugins and compaction rebuild the cache. Editing files, editing CLAUDE.md, changing permission mode, /rewind and spawning a subagent do not.
• Anthropic’s guidance is to keep each CLAUDE.md under 200 lines, use /clear between tasks, and set model: haiku for simple subagents.

Sourcing note: cache rules, settings and commands come from Claude Code’s official prompt caching, costs, MCP, memory and context window docs, re-checked on October 23, 2026 against Claude Code 2.1.309. The 33k/7k numbers are a single third-party measurement by Systima on an older version, so read them as that test’s result. Links at the bottom.

---

1. Measure first: /context and /usage

Run two commands in a session you actually use:

• /context shows the context window broken down by category: system prompt, tools, memory files (it also tells you which CLAUDE.md and auto-memory files loaded), skills and conversation. It includes optimization suggestions.
• /usage shows session token usage. After the first response it adds a Prompt cache (main) line, in this format (example from the docs):

Prompt cache (main):   14 requests · 91% of input tokens from cache · 2 misses (last 6m 10s ago, 310.2k tokens re-cached) · 1 expected rebuild (compaction or tool-result clearing) · warm (1h TTL, last activity 40s ago)

From v2.1.260, a miss also gets a cause, for example likely cause: tool definitions changed. On Pro, Max, Team and Enterprise plans, /usage also attributes usage to skills, subagents, plugins and MCP servers. Check the cache share first. If it is low, fix cache misses (section 3) before you trim anything.

2. What the “33k before your prompt” number means

Systima’s July breakdown, measured with a logging proxy on Claude Code 2.1.207 and Sonnet 4.5:

Component	Size	Tokens
Tool schemas (27 tools)	99,778 chars	~24,000
System prompt	27,344 chars	~6,500
First-message scaffolding	7,997 chars	(system-reminder blocks)
Total		~32,800

OpenCode came in at about 6,900 tokens, with 10 tools. Two things have changed since, or were easy to misread:

1. It is a stable prefix, and it gets cached. You pay full price when the cache is written, then a much cheaper cache read on each later turn, as long as nothing invalidates it.
2. MCP is no longer counted that way. Systima measured five MCP servers adding about 4,900 to 6,967 tokens per request. Current Claude Code turns on tool search by default. MCP tool definitions stay deferred until Claude needs one, and only names and server instructions load up front. If /context shows large MCP numbers, tool search is off for you. See the troubleshooting section.

So the 33k describes that particular setup. It isn’t a bill you pay in full on every turn.

3. Stop throwing the cache away

The prompt caching docs list which actions rebuild the cache and which keep it.

Rebuilds the cache (the next request re-reads everything at full input price):

• switching models, including a skill whose frontmatter sets a different model
• changing the effort level, on most models (on Opus 5.5, Sonnet 5.5, Haiku 5.5 and Fable 5.1 with an API key or subscription, the cache survives)
• the first fast-mode turn in a conversation (turning it off later keeps the cache)
• enabling or disabling a plugin
• connecting or removing MCP servers, but only when tools load up front. With deferred tools, the tool list is fixed from the first request.
• compaction, whether /compact or automatic
• the first conversation after a Claude Code upgrade, which starts uncached (auto-update applies on the next launch, never mid-session; DISABLE_AUTOUPDATER=1 lets you choose when)

Keeps the cache:

• editing project files, or editing CLAUDE.md (the change applies after /clear, /compact or a restart)
• changing permission mode or output style, or invoking a skill
• /recap, /rewind, and spawning a subagent

In practice: choose your model and effort before you start, keep plugins fixed for the whole session, and if you want to abandon a direction, use /rewind rather than /compact. Rewind returns to history the cache was built from. Compaction always rebuilds.

4. Set the right cache TTL

How you sign in	Main conversation	Subagents and everything else
Claude subscription, within plan usage	1 hour	5 minutes
API key, cloud provider, or subscription on usage credits	5 minutes	5 minutes

If you use an API key and step away for more than five minutes, the whole prefix is written again when you come back. From v2.1.242 you can change that:

// settings.json
{ "promptCacheTtl": "1h" }

You can also set CLAUDE_CODE_PROMPT_CACHE_TTL=1h. For subagents, use subagentPromptCacheTtl or CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL. A one-hour cache write is billed at a higher rate than a five-minute one. That’s why Claude Code drops to five minutes when you are paying per use. Turn it on only if you regularly pause and come back. To confirm which TTL your session wrote:

claude -p "hello" --output-format json
# look at usage.cache_creation: ephemeral_1h_input_tokens vs ephemeral_5m_input_tokens

Related: idle compaction summarizes a long, idle conversation shortly before a one-hour cache expires. If you would rather keep full history and pay for the rebuild, set "idleCompaction": false (v2.1.290+). Our Claude Code 2.1.302 note covers that toggle.

5. Trim CLAUDE.md properly

CLAUDE.md loads at the start of every session. Anthropic’s memory docs recommend keeping each file under 200 lines, because longer files use more context and Claude follows them less reliably. Systima measured a 72KB production instruction file adding about 20,000 tokens per request.

• Move workflow-specific instructions (PR review, migrations) into skills, which load only when used. See how to write a Claude skill.
• Put instructions for one part of the repo into path-scoped rules, which load only when Claude works in matching paths.
• @path imports don’t save tokens. Imported files are expanded into context along with the CLAUDE.md that imports them.
• Add a # Compact instructions section so that compaction keeps what matters:

# Compact instructions

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

6. MCP, CLI tools and built-in tools

• Prefer CLI tools such as gh, aws, gcloud and sentry-cli over an MCP server that does the same job. The docs say they are still more context-efficient, because they add no per-tool listing. Turn off servers you don’t use in /mcp.
• Check that tool search is actually on. It is off if you set CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS or ENABLE_TOOL_SEARCH=false, on models earlier than Opus 4 / Sonnet 4, on earlier Google Cloud Agent Platform models, and on Microsoft Foundry deployments hosted on Azure. In those setups every MCP tool loads up front, and Systima’s MCP numbers apply again.
• Denying a built-in tool doesn’t save tokens on default setups. A bare deny rule such as "WebFetch" stops Claude from calling the tool. With tool search active, the tool definitions in the request stay the same. Without tool search, the definition is removed, which invalidates the cache. Use deny rules for safety, not for token savings. For writing them, see our permissions guide.

7. Subagents, teams and thinking

• Subagents start their own context and use the five-minute cache. Systima measured one task split across two subagents growing from 121,000 to 513,000 tokens (4.2×). Use subagents when the parallel work is worth that cost.
• For simple subagent tasks, set model: haiku in the subagent’s configuration. If you switch the main session to Opus, subagents that inherit the session model switch with it.
• Agent teams use roughly 7× the tokens of a standard session when teammates run in plan mode, according to the costs docs.
• Lower reasoning cost with /effort, or on fixed-budget models with MAX_THINKING_TOKENS=8000.

8. Trim tool output with a hook

Tool output accumulates in the conversation, and a long test run is often the biggest single item. This PreToolUse hook comes from the official costs page. It rewrites test commands so that only failures reach Claude. Add it to settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "~/.claude/hooks/filter-test-output.sh" }
        ]
      }
    ]
  }
}

Save the script as ~/.claude/hooks/filter-test-output.sh and run chmod +x on it:

#!/bin/bash
input=$(cat)
cmd=$(echo "$input" | jq -r '.tool_input.command')

# If running tests, filter to show only failures
pattern='^(npm test|pytest|go test)( [^;&|<>`$#\\[:cntrl:]]*)?$'
if [[ "$cmd" =~ $pattern ]]; then
  filtered_cmd="$cmd 2>&1 | grep -A 5 -E '(FAIL|ERROR|error:)' | head -100"
  echo "$input" | jq --arg filtered "$filtered_cmd" \
    '{hookSpecificOutput: {hookEventName: "PreToolUse", updatedInput: (.tool_input + {command: $filtered})}}'
else
  echo "{}"
fi

Run /hooks and check that it appears under PreToolUse. To see it working, start claude --debug-file ./claude-debug.txt and ask Claude to run npm test. The log should contain a modified tool input keys line. The script needs jq installed.

9. Clear and compact on purpose

• /clear between unrelated tasks. Old context is billed again on every later message. Run /rename first so you can /resume the session later.
• Compact with a focus. For example, /compact focus on the auth bug fix keeps what you choose rather than what the automatic pass guesses.
• Move the automatic threshold. /autocompact 500k sets how full the window gets before automatic compaction runs. Compaction always rebuilds the cache, so run it at natural break points.

---

Troubleshooting

/context doesn’t show anything like 33,000 tokens. That’s expected. The 33k comes from Systima’s setup on Claude Code 2.1.207. Your version, model, MCP set and CLAUDE.md all change the total.

MCP tools take thousands of tokens in /context. Tool search is off for you. Check ENABLE_TOOL_SEARCH, CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS, the model, and whether you run on a cloud provider. The full list is in section 6.

The cache share in /usage is low. Read the likely cause text (v2.1.260+). The usual causes are a model or effort switch, a plugin toggled on or off, compaction, coming back after the TTL expired on an API key, or the first session after a Claude Code upgrade.

You edited CLAUDE.md and nothing changed. Editing doesn’t break the cache, and it doesn’t take effect immediately either. Run /clear or /compact, or restart the session.

Every resume after a break re-caches everything. You are probably on the five-minute TTL (API key or cloud provider). Set promptCacheTtl: "1h" and confirm with the claude -p ... --output-format json check in section 4.

One small task used a huge number of tokens. Look for subagent or team fan-out, and for a skill that switches models. Use /usage to see what the usage was attributed to.

FAQ

Is Claude Code wasteful compared with OpenCode? Its fixed prefix is bigger because it ships more tools: subagents, scheduling, worktrees. With caching and deferred MCP, the repeat cost is much lower than the headline number. If you never use those features, a minimal harness uses less context.

Does a bigger cache TTL always save money? No. A one-hour cache write is priced higher than a five-minute one. It pays off when you return to a session within the hour, and costs more if you don’t.

Do these tips apply to other agents? Mostly. GitHub’s own guidance for Copilot gives the same cache rules: don’t switch models mid-session, and set reasoning and tools before you start. See our Copilot AI Credits guide. For local models, the equivalent problem is KV-cache reuse. See fixing llama-server KV-cache reuse.

Sources

• How Claude Code uses prompt caching: what rebuilds or keeps the cache, TTL defaults, promptCacheTtl / subagentPromptCacheTtl (v2.1.242+), the ephemeral_1h_input_tokens check, the Prompt cache (main) likely cause (v2.1.260+), deny-rule behavior.
• Manage costs effectively: /usage cache line, /clear, compact instructions, model: haiku subagents, about 7× for agent teams, MAX_THINKING_TOKENS, CLI tools over MCP, the PreToolUse test-filter hook.
• MCP: scale with tool search: deferred tool definitions by default, when tool search is off, ENABLE_TOOL_SEARCH.
• Memory: under 200 lines per CLAUDE.md, path-scoped rules, imports expand into context.
• Context window: /context breakdown, focused /compact, /autocompact.
• Claude Code vs OpenCode token overhead (Systima): the 33k/7k measurement (Claude Code 2.1.207, Sonnet 4.5), 72KB file ≈ +20k tokens, 5 MCP servers ≈ +4.9 to 7k tokens before tool search became the default, the 4.2× fan-out case. A single third-party test.
• First published July 13, 2026. Re-verified and rewritten for Claude Code 2.1.309 on October 23, 2026. That rewrite corrected the MCP section: tools are now deferred by default.