Setting the prompt cache TTL in Claude Code
Published 29/10/2026
Claude Code caches your conversation so each turn re-reads it cheaply. The cache lasts for a set time after its last use, its TTL (time to live): five minutes or one hour. Step away for longer than that and your next turn rewrites the whole conversation at full price. (What that costs.)
What you get by default#
| Requests | On a Claude plan, within its usage | API key, usage credits or a cloud provider |
|---|---|---|
| Your main conversation | one hour | five minutes |
| Subagents, forks, compaction and other background work | five minutes | five minutes |
Once a plan goes past its limit and draws on usage credits, the main conversation drops to five minutes too.
Choosing your own#
Each setting takes 5m or 1h, and needs Claude Code v2.1.242 or later.
| For | Setting in settings.json | Or environment variable |
|---|---|---|
| The main conversation | promptCacheTtl | CLAUDE_CODE_PROMPT_CACHE_TTL |
| Subagents and background work | subagentPromptCacheTtl | CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL |
{
"promptCacheTtl": "1h",
"subagentPromptCacheTtl": "1h"
}FORCE_PROMPT_CACHING_5M=1 overrides everything and forces five minutes, which is handy when comparing the two.
Which to pick#
An hour costs more per write: at API list prices (checked 29/10/2026) an Opus one-hour write is 1.6× a five-minute one. It pays for itself when you pause for more than five minutes and come back, because each return skips a full rewrite. Short, continuous bursts of work gain nothing from it.
- Long sessions with breaks: one hour for the main conversation.
- Subagents that run for a while and pause, such as reviewers waiting on tests: try one hour for them too.
- Quick scripted runs: leave them at five minutes.
To check it is working, /usage shows a "Prompt cache (main)" line with the hit rate and whether the cache is warm.
Codex#
Codex's configuration has no cache TTL setting, so there is nothing to tune there.
Where ADE fits#
ADE's records and short briefings make a cold start cheap when one happens anyway: a fresh session begins from a generated handover rather than a long carried-over conversation. See context management for long-horizon work.