Claude Code prompt caching: TTL, cost, and cache misses
Claude Code prompt caching reuses unchanged context automatically. Learn the current TTLs, cache misses, API costs, and how to measure them.
Claude Code prompt caching automatically reuses server-side computation for the unchanged beginning of a request. A hit can make a response faster and reduce per-token API input cost.
It does not shrink your context window, erase old messages, or guarantee more subscription usage.
This site is independent and is not affiliated with Anthropic. Product behavior and primary sources below were checked on July 12, 2026.
How Claude Code prompt caching works
Claude Code sends the model's full context on every API request: system instructions, project context, prior messages, tool results, and the new message. The model itself does not remember the previous request.
Prompt caching lets the serving infrastructure match the exact unchanged start, called the prefix, against recently processed input. On a normal follow-up, Claude Code reads that prefix from cache and processes the new tail.
Anthropic's Claude Code caching documentation says there is no separate per-file or per-section cache.
Claude Code arranges stable material first and changing material last:
| Layer | Typical content | What changes it |
|---|---|---|
| System | Core instructions, loaded tools, output style | Tool-set or product changes |
| Project | Root CLAUDE.md, auto memory, unscoped rules | Session start, clear, or compact |
| Conversation | Messages, file reads, tool results | Every turn appends a new tail |
An early system change can force everything after it to be processed again. An ordinary new message usually preserves the earlier prefix.
Cache, context, and compaction are different
| Concept | What it changes | What it does not do |
|---|---|---|
| Context window | The information Claude can use on this turn | It does not describe whether computation was cached |
| Prompt caching | Reuses computation for an exact prefix | It does not remove input from the context window |
| Compaction | Replaces older history with a shorter summary | It is not a cache-saving switch |
A cached 50,000-token prefix still occupies 50,000 tokens of context. It can still contain irrelevant or contradictory material.
The context engineering guide explains how to choose better input. Caching only changes how repeated input is processed.
Compaction has its own job. Claude Code creates the summary through a cache-safe request that can reuse the existing prefix. The next normal turn uses the shorter history and rebuilds the conversation layer.
Anthropic's context-window guide documents what compaction preserves and reloads.
Current cache lifetimes and API costs
TTL means time to live. It is an inactivity timer, and a cache hit refreshes it.
| Claude Code route | Default TTL | Important detail |
|---|---|---|
| Main conversation on a Claude subscription | 1 hour | Requested automatically; usage is included in the plan |
| Subscription using paid usage credits | 5 minutes | Claude Code drops to the billed-use default |
| API key or supported third-party provider | 5 minutes | One hour can be enabled, with a higher write rate |
| Subagent on any plan | 5 minutes | It starts and warms a separate cache |
With an API key, ENABLE_PROMPT_CACHING_1H=1 requests the one-hour TTL. FORCE_PROMPT_CACHING_5M=1 forces five minutes for debugging or measurement.
Provider model, region, and gateway support can differ, so neither variable proves a cache hit by itself.
Anthropic's current API pricing lists five-minute writes at 1.25 times base input price, one-hour writes at 2 times, and cache reads at 0.1 times.
Those are operation multipliers, not total-task savings. Fresh input, output, writes, and reads can all appear in one task.
On a subscription, do not convert cache-read tokens into dollars or a promised amount of session allowance. Claude Code pricing owns the wider plan and billing decision.
What causes a cache miss
Current documented causes include:
- switching models or effort level;
- enabling fast mode for the first time deep in a conversation;
- reloading a plugin whose MCP server changes tool definitions loaded into the prefix;
- adding a deny rule that removes an entire visible tool;
- changing tool definitions that are loaded into the prefix;
- running
/compactand replacing the conversation history; - starting after an upgrade changed Claude Code's instructions or tools;
- returning after the active TTL expired.
MCP needs a qualification. Deferred MCP tools, the default on supported models and configurations, can connect or change without disturbing the cached prefix. Upfront definitions can invalidate it.
The API vs MCP vs CLI guide covers the broader integration decision.
Ordinary messages, repository edits, Skills, /recap, and /rewind normally preserve the earlier prefix.
Editing a root CLAUDE.md mid-session also leaves the cache alone because the edit does not apply until /clear, /compact, or restart. See Claude Code memory for the loading boundary.
Measure reads and writes instead of guessing
Two response fields matter:
cache_creation_input_tokens: input written to the cache on that turn;cache_read_input_tokens: input served from the cache on that turn.
Anthropic's API prompt-caching reference defines both fields. Its Claude Code guide recommends a status-line script that reads current_usage for live visibility.
A high read-to-creation ratio suggests a stable prefix. Repeated creation can indicate expiry or a changing model, effort, tools, or startup state.
/context is not cache evidence. It shows what occupies the context window. /usage shows session usage and plan activity.
Anthropic's cost guide says its API dollar figure is a local estimate. The Claude Console Usage page is authoritative for first-party API billing.
A controlled TTL test you can reproduce
We have not run and retained this experiment, so this guide reports no measured saving or winner. The procedure is designed to test the documentation rather than assume it.
Create a clean test repository with one frozen reference document, three equally short factual questions, and a status-line logger for cache creation, cache reads, model, effort, input, and output.
Run the five-minute condition
Use a dedicated API key, force the five-minute TTL, ask two questions within two minutes, wait six minutes, then ask the third.
Run the one-hour condition
Enable the one-hour TTL in an equivalent frozen copy and repeat the same timing, model, effort, prompts, and tools.
Repeat both three times
Alternate order and preserve errors, timestamps, Claude Code version, git commit, and redacted usage logs.
Compare within each run
Report creation, reads, fresh input, output, and latency. Do not infer subscription savings from the API-key test.
Use separate clean copies because Claude Code's prefix includes its working directory and startup state. Keep the repository, git status, model, effort, plugins, MCP servers, and Claude Code version fixed inside each run.
For a delegated task, a Claude Code subagent starts its own five-minute cache with no first-call hit. Its call and result append to the parent, so the parent's prefix remains intact.
That is a cache fact, not a reason to use or avoid a subagent.
What caching cannot prove
Caching does not validate your context, improve a weak prompt, guarantee the same sampled answer, or repair an overloaded conversation. It also does not establish how cached input maps to a subscription's remaining allowance.
Results from one API-key test cannot be generalized to Bedrock, Google Cloud, Foundry, a custom gateway, claude.ai chat, or another machine and directory. Measure the route you actually use.
Does Claude Code use prompt caching automatically?
Yes. Claude Code manages prompt caching automatically unless you disable it. You normally do not add API cache breakpoints yourself when working in the Claude Code terminal or extension.
How long does the Claude Code prompt cache last?
The main conversation uses one hour on a Claude subscription. API-key and supported provider sessions default to five minutes, as do subagents. Paid usage credits also switch the subscription session to five minutes.
Does /compact clear the prompt cache?
Compaction replaces conversation history with a summary, so the conversation prefix changes. The summary request can reuse the old prefix, while the next normal turn builds a cache around the shorter history.
Do Claude Code subagents share the parent cache?
No. A subagent starts a separate conversation and warms its own five-minute cache. Its first call starts cold. The parent cache remains intact because the subagent request and result append to the parent conversation.
The useful rule is modest: keep a task's model, effort, and loaded tools stable when practical, then inspect creation and read tokens before changing your workflow.