The Prompt Caching Guide

Prompt caching serves the repeated prefix of your context — system prompt, CLAUDE.md, reference files — at roughly one tenth of normal input price. Cache reads cost about 0.1× base input; writes cost 1.25× (or 2× for the long-lived tier); entries expire after minutes of inactivity. Structure your context so the stable part stays byte-identical, and the largest component of every request becomes nearly free.

The Pricing Model in One Table

On the Claude API, caching has three price points relative to base input cost:

Normal input          1.0×   (uncached tokens)
Cache write           1.25×  (first time a prefix is stored; 5-min TTL)
Cache write (1-hour)  2.0×   (long-lived tier)
Cache read            ~0.1×  (every hit thereafter)

The break-even math is friendly: with the default 5-minute TTL, a prefix that gets reused even once has paid for its write premium (1.25× + 0.1× < 2 × 1.0×). A 10,000-token preamble read forty times a day costs about a tenth of what it would uncached — which is how a single structural fix produced the 73% bill reduction described in why optimize tokens. Each read also refreshes the entry's TTL, so steady traffic keeps the cache warm indefinitely.

The One Rule: Caching Is a Prefix Match

The cache key is the exact byte sequence of your context from the top. Any change anywhere in the prefix invalidates everything after it. This single fact explains almost every disappointing hit rate:

✓  System prompt / CLAUDE.md        ← stable, cache-safe
✓  Reference docs, conventions      ← stable, cache-safe
─────────────────────────────────────
✗  "Today's date is 2026-07-17"     ← busts everything below
✗  Current task list, session notes ← belongs at the END

A timestamp on line 3 of your system prompt means the prefix differs every day — so the other 9,900 tokens below it are re-processed at full price on every request. The fix costs nothing: stable content first, volatile content last. If you call the API directly, mark the end of the stable block explicitly with "cache_control": {"type": "ephemeral"}; note that very short prefixes (roughly under 1,000–4,000 tokens, depending on model) are below the minimum and silently won't cache. Claude Code handles breakpoints automatically — your job is only to keep the prefix stable.

The Failure Modes: Thrash and Expiry

Cache thrash

Thrash is paying the 1.25× write premium over and over without ever collecting the 0.1× reads — the cache equivalent of buying a season pass daily. Classic causes:

• Volatile content early in the prefix — dates, run IDs, randomly ordered lists (serialize deterministically; sort your keys).
• Rotating between variants — alternating system prompts, or tools added/removed per request. Tools render at the very front of the context, so a changing tool set invalidates everything.
• Editing the preamble mid-session — every edit re-writes the whole prefix. Append new instructions at the end instead.

The signature of thrash in API usage data: cache_creation_input_tokens high and recurring, cache_read_input_tokens near zero. You're paying a premium for storage you never use.

TTL expiry

Default cache entries live about five minutes from last use. Work in bursts with 20-minute gaps and every burst starts with a full-price re-write. Options: batch related requests together, keep sessions active rather than idling, or (direct API users) pay the 2× write for the 1-hour tier when gaps are structural. An expired cache isn't an error — it's just money.

Diagnosing Your Hit Rate

A healthy interactive session runs a 60–80% cache hit rate. Below 30%, your context structure is actively costing you money. Terse's session monitor shows live cache percentages per turn, and Terse Doctor flags the two pathologies by name — low hit rate (stable content not leading the prefix, or sessions idling past TTL) and write thrash (repeated writes with no reads) — so the fix is pointed at the actual cause instead of guessed. Pair the structural fix with a trimmed system prompt and the preamble becomes both small and nearly free; the team case study that went from 28% to 71% hits saved four figures monthly on this alone.

Frequently Asked Questions

How much cheaper are cached tokens?

Cache reads cost roughly 10% of normal input price on the Claude API. Writes carry a one-time premium — about 1.25x base for the default 5-minute tier, 2x for the 1-hour tier — which a single reuse already repays.

Why is my prompt cache hit rate low?

Almost always because the prefix isn't byte-stable: a date or ID near the top of the system prompt, tools changing between requests, or a preamble edited mid-session. Any byte change invalidates everything after it. Move volatile content to the end and keep the stable block frozen.

What is cache thrash?

Repeatedly paying the cache-write premium without collecting reads — writes high, reads near zero in your usage data. It means your prefix changes on every request, so each write is wasted. Deterministic, stable prefixes are the fix.

Does Claude Code cache automatically?

Yes — Claude Code places cache breakpoints for you. What it can't do is make an unstable prefix stable: if your CLAUDE.md leads with volatile content, the automatic caching has nothing reusable to work with. Ordering is still your job.

Further Reading

• Terse Blog — all token optimization guides
• System Prompt Bloat — shrink the prefix you're caching
• Real Results — a team's 28%→71% hit-rate story
• Terse for Claude Code — live cache monitoring