Prompt caching: cut Claude Code cost and latency

Prompt caching lets the model reuse a stable prefix instead of re-processing the same tokens on every turn. In Claude Code, caching is automatic. You do not set breakpoints in code or configure anything in a dashboard. What you control is how you structure your sessions and context so the stable prefix stays stable. That habit is where the savings come from.

How does prompt caching work in Claude Code?

Every time you send a message, Claude Code assembles a context window. It places the most stable content first: your CLAUDE.md rules, any injected files, and the system instructions that rarely change. The live part of the conversation goes at the end.

The model checks whether the leading bytes of that context match a recent request from the same session. On a match, those tokens are served from cache at a fraction of normal input cost. On a miss, they are processed normally and the result is written to cache for the next call.

The cache key is byte-exact. Change anything before the stable boundary and you get a miss. This is why your habits matter more than any configuration setting.

What gets cached?

The stable prefixthe unchanging portion of context that the model can serve from cache instead of reprocessing is eligible for caching. In a Claude Code session this typically includes:

• The contents of CLAUDE.md (rules, conventions, project layout)
• Any long files you asked Claude to read at the start of a task
• Injected documentation or spec files
• The implicit system instructions Claude Code always includes

Not cached: your current message, recent assistant replies, and anything you vary between turns.

Minimum token threshold

The stable block must be at least 1,024 tokens on Sonnet and Opus models. A CLAUDE.md with real project conventions, plus one or two injected files, easily clears this. Thin, minimal CLAUDE.md files may fall below the threshold and receive no cache benefit at all.

How much does prompt caching cost?

Cache writes cost slightly more than normal input. Cache reads cost much less. The maths pays off as soon as a session has a few turns.

Numbers verified against Anthropic docs in June 2026. Always confirm current pricing at docs.anthropic.com/en/docs/about-claude/pricing before capacity planning.

Break-even point

With a 5-minute TTL (the default for a live session):

• Write cost: 1.25x
• Each read: 0.1x
• Break-even after the second call (1.25 + 0.1 = 1.35x vs. 2.0x uncached)

Any task with more than two turns on a stable context window wins on cost.

Before and after: a real session

An agent that runs 50 turns. Each turn includes a 4,000-token stable context (rules, injected docs) and a 500-token live message.

The dominant cost shifts from 225,000 normal tokens to: one write (4,000 x 1.25 = 5,000 effective tokens), plus 49 reads (4,000 x 0.1 x 49 = 19,600 effective tokens), plus 50 live messages (500 x 50 = 25,000 tokens). Total: roughly 49,600 effective tokens vs. 225,000. That is a 78% reduction on input costs for a routine agentic task.

Habits that make caching pay

Keep the stable content at the top of context

Claude Code reads CLAUDE.md first. Put your project conventions, architecture notes, and style rules there, not in ad-hoc messages you type mid-session, as covered in rules and memory files. Rules in CLAUDE.md sit in the stable prefix. Rules typed as a follow-up message sit in the live portion and are never cached.

# CLAUDE.md example (stable prefix content)
 
## Stack
Next.js (App Router), TypeScript, Tailwind.
 
## Conventions
Functional components, one per file. Co-locate tests with the source.
 
## Commands
Build: npm run build · Test: npm test · Lint: npm run lint

The more real convention you consolidate here, the larger and more valuable the cached block becomes.

Inject long documents at session start, not mid-conversation

If a task needs a spec file, a large data file, or a long code file, read it at the start of the conversation. Claude Code places injected content in the stable prefix region.

# Start a session with the spec file already in context
claude "Read docs/checkout-flow.md then help me add the discount-code step"

Injecting the same file mid-conversation, after several turns of back-and-forth, places it later in the context window where it is less likely to be part of the stable prefix.

Reuse sessions with --continue

Each new claude invocation starts a fresh context. The stable prefix gets written to cache on the first turn and stays warm while the session is active. --continue picks up the most recent session, keeping the cache warm across interruptions. For what carries over between runs, see Claude Code session state.

# Resume where you left off, cache already warm
claude --continue

Starting a new session for each small question wastes the write cost and never benefits from reads.

Do not edit the top of context mid-session

If you ask Claude to update CLAUDE.md or change the injected files during an active session, the stable prefix changes and every subsequent turn pays a write cost again. Batch those changes to end-of-session or start-of-next-session. Work on the live task, then tidy the rules file when you close out.Common gotchaThe trap is asking Claude to "fix a typo in CLAUDE.md" or "add a rule" mid-task.Because the cache key is byte-exact, that one edit invalidates the whole prefix and re-bills a full write on every remaining turn, so a five-character tweak can cost more than the work itself. Note the change in a scratch list and apply it once the task is closed out.

Context layers and caching

Think of your session context as layers, from most stable to least:

Layer 1 is written once per session (or less, if you reuse sessions). Layer 2 is written on the first turn that includes those files. Layers 3 and 4 are always live. The savings accumulate in layers 1 and 2.

Checking cache behaviour with /cost

After any multi-turn task, run /cost inside the Claude Code session to see a breakdown of token usage, including cached vs. live tokens. If the cached token count is low on a long session, your stable prefix may be shorter than 1,024 tokens, or you may have changed it mid-session.

# Inside a running Claude Code session
/cost

The output shows input tokens, output tokens, and how many were served from cache. Use this during development to verify your habits produce cache hits.

How long does the cache last?

The default TTL for a Claude Code session is 5 minutes. Every cache read resets the clock. An active session where you send messages every minute or two stays warm indefinitely after the first write. A session where you step away for 10 minutes will pay another write cost on return, but then stays warm again.Common gotchaDo not assume a session stays warm just because it is still open. The clock is wall-clock, not turns, so a coffee break or a slow read past five minutes silently expires the cache and re-bills a full write on your next message.For a long pause on a big context, finish the current ask before you step away.

For long-running background agents or automated tasks that call the model less frequently, the underlying platform can use a 1-hour TTL. That costs more to write (2.0x vs. 1.25x) but avoids repeated write charges on low-frequency workloads. Claude Code manages this automatically based on call patterns.

When does caching not help?

• Single-turn questions. One call per session means you pay the write cost and never benefit from a read.
• Sessions with very short context. If your CLAUDE.md is minimal and you inject no files, the stable prefix may not clear the 1,024-token floor.
• Frequent edits to CLAUDE.md mid-session. Each edit busts the cache for the rest of the session.
• Tasks where every message is a fresh context. Automated scripts that start a new claude process per item get one write and zero reads per item.

For automated scripts that run many items with a shared system context, pass the shared context once via a shared CLAUDE.md or injected file so all items benefit from the same stable prefix.

Related guides

Caching reduces the cost of tokens you are already sending. The complementary skill is keeping your context window from growing uncontrollably across a long session. Combine a stable, cached prefix with disciplined context hygiene: close sessions when a task is done, start fresh ones for unrelated tasks, and keep your live context relevant to the current step. To see where caching sits in the bigger picture, read token usage and cost.