How to cut your Claude Code token usage by 20x

You do not pay for the one-line question you just typed. You pay for everything the agent must resend so the model can pretend it remembers the conversation – and for whether that payload hits a warm prompt cache.

The 20x is one specific number: Anthropic bills a token read from the prompt cache at 0.1x the input rate (cache read), and a token written into the cache at 2x (cache write). Same content, twenty times the price, decided by whether the cache was warm when you hit enter.

Prompt length has almost nothing to do with your bill. Context size multiplied by cache temperature is your bill.

Why a one-line question can be expensive

The Messages API is stateless. A conversation only exists because the client resends the entire history every turn – system prompt, tool definitions, instruction files, every previous message, every file read, every tool result.

The cost of turn N is the size of turns 1 to N−1. A short question at the end of a long session drags everything before it along.

What is already in context before you type

• Harness system prompt – tool-use rules, environment, git instructions.
• Tool definitions – full JSON schema per tool. MCP servers add theirs. Deferred tools cost only their name until used.
• Instruction files – ~/.claude/CLAUDE.md, the project CLAUDE.md, and everything under ~/.claude/rules/. Re-read every turn.
• Skill catalogue – each skill's name and one-line description. Bodies load only on invocation.

Instruction files are the ones to audit: paid on every turn of every session, and entirely under your control.

How the caching actually prices out

Anthropic caches a prefix of the request. Next turn, if the first N tokens are byte-identical, they bill as a cache read. Reads are 0.1x, writes are 1.25x for the 5-minute TTL and 2x for the 1-hour one. Every hit resets the TTL, so an active session stays warm indefinitely.

Expiry is where it bites:

240,000-token conversation
 
warm    240,000 × 0.1  =   24,000
expired 240,000 × 2    =  480,000

The mechanism is not Claude-specific – every stateless chat API resends context, and OpenAI and Google cache too. The numbers above are Anthropic's, and the tooling below is Claude Code's.

How to fix it in Claude Code

Fix 1: scope your instruction files

Any markdown file under ~/.claude/rules/ can declare what it applies to:

---
paths:
  - "**/*.kt"
  - "**/*.sql"
  - "**/migrations/**"
---
 
# Database conventions

It then loads only once a matching file enters the conversation. Without the header, your Postgres conventions load while you edit a React component, and again next turn, forever.

Find the unscoped ones:

grep -L '^---' ~/.claude/rules/**/*.md
wc -c ~/.claude/CLAUDE.md ~/.claude/rules/**/*.md | tail -1

Bytes divided by four is a rough token count. The same applies to CLAUDE.md itself – it should hold routing and behaviour, not inlined config samples that belong in a scoped rule.

Fix 2: one conversation per task

If a question does not need the history, /clear first. A new session carries the system prompt and nothing else, and that prefix is identical between sessions so it usually hits cache anyway.

Fix 3: watch the clock, not the size

A 300,000-token conversation you are actively working in is cheap – every turn lands inside the TTL and refreshes it. The same conversation after lunch costs 2x on all 300,000 tokens.

Closing the app flushes nothing; the cache is server-side on a timer. Starting a new session is not what costs – resuming a large old one is. Note that any system-prompt change invalidates the cached prefix, so editing CLAUDE.md or installing a plugin buys you one rebuild on the next session.

Fix 4: keep long sessions light

Anything entering context stays for the session and is resent every turn. Screenshots are the usual offender, along with large file reads and full test logs. Need a big artifact for one decision? Make the decision, then /clear.

Compact when a task ends rather than waiting for auto-compact at the limit – every turn before that fires was paid at near-maximum context.

Same idea on Codex, Gemini, and the rest

The multipliers change by vendor. The shape of the problem does not.

Every coding agent that talks to a chat API is still stateless: turn N resends history, tools, and instruction files. A warm prompt cache (or the provider’s equivalent) is what keeps that from pricing like a full re-read. Cold cache, edited prefix, or a giant always-on instruction blob hurts the same way whether the product is branded Claude, GPT, or Gemini.

Map the files, then apply the same four fixes:

Practical carry-overs:

1. Keep instruction files thin and scoped. Codex walks AGENTS.md from repo root down to cwd and caps combined project docs (32 KiB by default) – nest package-specific guidance instead of one novel at the root. Gemini discovers GEMINI.md hierarchically; you can set context.fileName to AGENTS.md if the team standardizes on one file. Claude’s path-scoped rules are the same idea under another name.
2. One task per session. /clear (or the local equivalent: new thread, new Codex turn without the old transcript) when history is not needed.
3. Do not resume a huge cold session. TTL and write pricing differ – Anthropic’s 0.1x / 2x spread is not universal – but an idle large context still forces a rebuild somewhere on the bill or the rate limit.
4. Disable idle MCP servers. Every enabled server’s schema rides along; Codex’s own pricing notes call this out explicitly.

Do not copy Anthropic’s 20x into a Codex or Gemini spreadsheet. Read the current cache-read / cache-write (or “cached input”) line for the model you actually use, then measure. The hygiene is portable; the constants are not.

Block the expensive turn automatically

Hygiene cuts the floor. It does not stop you from hitting Enter on a 300k-token thread after lunch. That is what context-cost-guard is for: a UserPromptSubmit hook that runs before the request leaves, and blocks once when a turn looks cheap but will rewrite a cold cache.

You do not paste Python into ~/.claude or edit settings.json. Install the plugin (Claude Code Desktop or terminal – both work; needs python3 on PATH):

/plugin marketplace add JanBancerewicz/context-cost-guard
/plugin install context-cost-guard@context-cost-guard

Then restart Claude Code (or /reload-plugins). Hooks load at session start; a restart is the reliable activation. The plugin merges its hook with any hooks you already have – it does not overwrite your config.

Source, MIT license, and the ~130-line script: github.com/JanBancerewicz/context-cost-guard. No network calls – it only reads your local session transcript and a tiny snooze file under ~/.claude/.

When it blocks – both must be true:

• last-turn context ≥ 60,000 tokens (input + cache read + cache write fields), and
• idle ≥ 55 minutes since the last assistant timestamp (tuned for a ~1h TTL)

When it stays quiet – small context, short idle, you are inside the 5-minute snooze after a block, or anything goes wrong reading the transcript (fail-open: errors never trap a turn).

After a block the card looks roughly like:

This turn will cost much more than it looks.
 
  Conversation context : 379,250 tokens
  Idle                 : 94 min  (cache likely expired after 60 min)
  Est. turn cost       : ~758,500 vs ~37,925 token-equivalents
 
  /clear    new topic – cheapest, start from zero
  /compact  same thread, summarized
  resend    send the same prompt again to continue anyway

Warm vs cold numbers are illustrative (context × 0.1 vs context × 2), not an invoice. /clear and /compact are the cheap exits; resend within five minutes always goes through so the guard cannot lock you out.

Caveat worth knowing: the hook infers expiry from idle time, assuming a 1-hour prompt-cache TTL. On routes that use a 5-minute TTL (or similar overage behavior) it can under-warn – the cache may already be cold while idle is still under 55 minutes. Defaults live at the top of the plugin script if you fork; most readers should just install and leave them.

The same gate pattern (observe size + idle → block before send → explain → snooze → fail open) ports to other agents; this plugin is the Claude Code CTA because that is where UserPromptSubmit already exists.

Numbers from one session

first API call, before any work     109,618 tokens of context
context by end of session           274,376 tokens
average context re-read per call    187,867 tokens
 
most expensive single turn – a two-line question, no tools:
  cache rebuild   475,888   97.8%
  cache read        2,222    0.5%
  the answer        8,335    1.7%

That turn's answer was 1,667 output tokens. The rest was a conversation being written back into a cache that had expired 34 minutes earlier.

Scoping the instruction files in that setup took 155,875 bytes of always-on context – about 39,000 tokens per turn – down to 6,925. Nothing was deleted; the rules still load when they are relevant.