Claude Code Cache TTL: Managing Prompt Cache Lifespans, Costs, and Context Drift

Anthropic prompt cache entries have a default lifetime of 5 minutes that refreshes at no additional cost upon reuse, measured from the moment a request begins processing. When a developer pauses to review a code diff, consult architectural diagrams, or answer a teammate, any idle gap exceeding 5 minutes invalidates the cached prefix. The next interaction then forces a complete re-read and re-write of the entire context window. Understanding how prompt cache lifespans interact with terminal workflows separates cost-controlled agentic engineering from runaway API bills. Detailed guidelines can be verified directly in the Anthropic prompt caching documentation.

Claude Code cache TTL defines how long cached conversation prefixes, system prompts, and tool schemas remain in Anthropic's prompt cache before expiring, defaulting to 5 minutes with a configurable 1-hour option. Large language models do not store conversational state between network calls. Each message sent through Claude Code constructs an API request containing the entire interaction state: the underlying system instructions, project configuration files, connected tool schemas, preceding conversation turns, and tool outputs. Without prompt caching, the API reprocesses every token from scratch on every turn, causing input costs to scale quadratically as sessions lengthen.

Prompt caching addresses this compounding overhead by allowing Anthropic's inference engine to reuse pre-computed Key-Value attention tensors across sequential API turns. Anthropic prompt cache reads provide up to a 90% discount on input token costs compared to standard uncached input pricing, reducing latency by up to 85% for long prompts. However, writing tokens to the cache is not free. Initial cache writes incur a 25% cost premium over standard input tokens for 5-minute entries, while 1-hour cache writes cost 2x base input tokens (double the standard input token rate). Consequently, prompt caching is not a passive discount; it is a financial tradeoff that requires enough subsequent cache reads within the TTL window to amortize the initial write surcharge.

• Claude Prompt Caching TTL: Lifespans, Eviction Rules, and Persistent StorageClaude prompt caching TTL determines how long pre-computed KV attention states remain in server memory before eviction....
• Managing the GitHub Copilot Context Window & Token LimitsManaging the active token memory in GitHub Copilot is essential for complex repository operations. This guide details...
• Claude Code Cache Limits: Breakpoints, Thresholds, and Cost ManagementClaude Code prompt caching relies on Anthropic's four-breakpoint ceiling, strict minimum token thresholds, and a...
• How to Set Claude Code Cost Limits: Budget Ceilings and Token ManagementA Claude Code cost limit is a financial or token consumption ceiling configured via Anthropic Console spend controls,...
• Claude Code Message Limit: Quotas, Compaction, and Large-Context WorkaroundsClaude Code message limits define the maximum prompt token size and message frequency allowed in a CLI session before...
• Claude Code Skills: How to Create, Install, and Use Custom SkillsClaude Code skills are SKILL.md instruction files that extend what Claude can do, automatically loaded when relevant to...

More on this subject: Claude and Claude Code (325 guides)

Claude Code provides two distinct cache durations: the standard 5-minute TTL (5m) and an extended 1-hour TTL (1h). Selecting the right setting requires balancing write surcharges against developer pause patterns and billing structures. Review the Claude Code prompt caching guide for release notes. The table below contrasts operational characteristics, cost formulas, and recommended settings for 5-minute and 1-hour cache TTL configurations:

The cost arithmetic reveals the central tradeoff: an extended 1-hour TTL charges 2x the standard input token rate on initial cache creation.

To evaluate when the 1-hour TTL saves money versus when it increases token expenditure, consider the economic difference across two standard engineering patterns:

In an automated testing runner or headless script where Claude Code executes continuous commands with brief 30-second gaps, the default 5-minute TTL writes once with a 25% write surcharge and reads from cache across all subsequent turns. Under a 1-hour TTL, that same continuous run pays the higher one-hour write rate on turn one without gaining any retention benefit from the longer window, because no pause ever approaches the 5-minute expiration boundary. For rapid, continuous terminal sessions, the 5-minute TTL is consistently more economical.

In interactive human development, engineers pause regularly to review git diffs, run local unit tests, or consult architectural specifications. Pauses exceeding 5 minutes routinely cross the default expiration threshold. In a four-turn refactoring session with 10-minute pauses between prompts, a 5-minute cache expires after every pause:

• Turn 1: Initial cache write establishing the prefix.
• Turn 2 (after 10-minute pause): Cache expired. Full re-read and re-write of the context window.
• Turn 3 (after 10-minute pause): Cache expired. Full re-read and re-write of the context window.
• Turn 4 (after 10-minute pause): Cache expired. Full re-read and re-write of the context window.

In that interactive scenario, the session pays the full cache write penalty four separate times, recompiling the entire prompt context from scratch on every turn. Under the 1-hour TTL, the cached prefix remains warm throughout every 10-minute pause. Turn 1 establishes the cache at 2x base input tokens, while Turns 2, 3, and 4 hit the warm cache and receive the discounted read rate. The 1-hour TTL cuts total input expenditure across the session while eliminating turn latency caused by rebuilding Key-Value tensors.

Eliminate Repetitive Prompt Cache Rewrites with Intelligent Workspaces

Keep your Claude Code prompt cache clean and fast. Offload large codebase docs, API specifications, and multi-agent context to Fast.io workspaces with built-in hybrid search over MCP. Start a 14-day free trial on any monthly plan.

Start 14-Day Trial

Claude Code evaluates prompt cache retention through two dedicated settings introduced in version 2.1.242: promptCacheTtl and subagentPromptCacheTtl. These settings give developers granular control over the main interactive conversation and background tasks.

Global configurations belong in ~/.claude/settings.json, while project-specific configurations belong in .claude/settings.json within your repository root. A complete configuration declaring 1-hour lifespans for both interactive coding and background tasks takes this shape:

{
  "promptCacheTtl": "1h",
  "subagentPromptCacheTtl": "1h"
}

Both keys strictly accept "5m" or "1h". Any other string value is ignored, causing Claude Code to fall back to default bucket rules. You can also export environment variables in your shell configuration or CI pipeline:

export CLAUDE_CODE_PROMPT_CACHE_TTL=1h
export CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL=1h

When multiple configuration mechanisms coexist, Claude Code resolves the active TTL using a strict six-tier priority ladder:

1. FORCE_PROMPT_CACHING_5M=1: An environment variable that immediately forces the 5-minute TTL across all requests, overriding all other settings.
2. The bucket environment variable: CLAUDE_CODE_PROMPT_CACHE_TTL for main conversations or CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL for subagents and helper tasks.
3. The bucket configuration setting: promptCacheTtl or subagentPromptCacheTtl read from the merged project or user settings.json.
4. Subagent frontmatter configuration: The cacheTtl property defined under the experimental block in a subagent definition file (supported in Claude Code v2.1.248 and later).
5. ENABLE_PROMPT_CACHING_1H=1: An environment variable that requests the 1-hour TTL across all requests unless overridden by higher-priority bucket settings.
6. The request bucket default: Resolves based on billing type. Claude subscriptions within plan limits grant 1 hour to the main conversation and 5 minutes to everything else. API keys, usage credits, and cloud platforms grant 5 minutes across the board.

A frequent source of runaway token bills in Claude Code is the habit of feeding large static files directly into the prompt context. Developers routinely use @docs, file-read commands, or clipboard pastes to provide Claude with comprehensive OpenAPI specifications, database schemas, framework documentation, or system logs.

While this approach gives Claude immediate visibility, it severely damages prompt cache economics. When a 40,000-token API specification is pulled into the conversation history, it becomes an immutable part of the prompt prefix for all subsequent turns. Under the default 5-minute TTL, every pause that exceeds 5 minutes invalidates the entire cache. On the next prompt, Anthropic bills the re-read of that 40,000-token file at the full cache write rate rather than the discounted read rate, repeatedly billing write surcharges on every expired turn.

When multiple subagents are spawned, the penalty multiplies. Each subagent reads the file into its own isolated context, writing identical 40,000-token prefixes into independent cache slots. A session with four subagent invocations can easily consume hundreds of thousands of tokens purely in redundant cache-write overhead for static documentation that never changed.

Beyond financial waste, large static files trigger severe context drift. Filling the context window with reference documentation forces Claude Code to initiate early compaction. During compaction, detailed architectural instructions and nuances from earlier user prompts are condensed into lossy summaries. Critical constraints are forgotten, and the model begins producing hallucinations or contradictory code edits.

claude mcp add --transport http fast-io https://mcp.fast.io/mcp/code

{
  "mcpServers": {
    "fast-io": {
      "type": "http",
      "url": "https://mcp.fast.io/mcp/code"
    }
  }
}

Maximizing prompt cache efficiency in Claude Code requires treating prompt structure as a carefully managed hardware cache. Applying these five operational practices prevents unnecessary cache invalidations and keeps token bills predictable:

1. Match cache TTL to operational cadence: Use 1-hour TTL ("promptCacheTtl": "1h", "subagentPromptCacheTtl": "1h") on developer workstations where human interruptions, code testing, and architecture reviews create pauses between 5 and 60 minutes. Use 5-minute TTL (FORCE_PROMPT_CACHING_5M=1) in automated CI/CD runners where turns execute in rapid, unbroken succession.

2. Freeze the prompt prefix during active tasks: Treat system prompts, MCP tool definitions, and repository guidelines as immutable while working on a feature. Avoid connecting or disconnecting MCP servers mid-task, avoid modifying plugins, and refrain from editing CLAUDE.md in the middle of a refactoring session. Configure your tooling environment before opening Claude Code.

3. Extend subagent retention during multi-stage tasks: When designing workflows that invoke subagents intermittently, configure "subagentPromptCacheTtl": "1h". This ensures auxiliary agents retain their compiled Key-Value caches across tasks, avoiding repeated write fees on their tool definitions and instructions.

4. Schedule compaction at logical project boundaries: Compaction wipes conversation history and rebuilds the prompt cache. Avoid running /compact in the middle of diagnosing a complex bug where recent compiler outputs and error traces are needed. Run /compact when completing a discrete milestone or switching to a new ticket.

5. Monitor cache hit rates and token expenditure: Regularly inspect cache performance using Claude Code's /usage command (or /cost on earlier releases). For organization-wide observability, configure the OpenTelemetry exporter to stream cache read and cache creation metrics to your monitoring dashboard, identifying subagents and repositories suffering from chronic cache invalidation.