Claude-thermos Tool Prevents Claude Code Prompt Cache Expiration

Addressing Claude Code Cache Expiration

claude-thermos is a new utility designed to mitigate an issue within Claude Code where the prompt cache can expire. This expiration occurs when the main agent waits on a subagent for more than five minutes, leading to the re-encoding of the entire conversation history at a higher cost rather than retrieving it from the cache at a lower rate.

Mechanism of Cache Expiration

Claude Code's prompt cache has a five-minute Time-To-Live (TTL). If no requests are made on the same cache prefix within this period, the cache expires. The primary cause for this gap is when a main agent is blocked by a subagent. Subagents have different system prompts and tool sets, meaning their requests do not refresh the main agent's cache. While the subagent is active, the main agent's cached history ages and expires, forcing a full re-encode upon the subagent's return.

Cost Implications

Re-encoding large conversation histories after cache expiration can be expensive. Measurements across 185 local sessions indicated that these rebuilds accounted for approximately 22% of the total API bill. This cost is incurred for re-encoding content that was recently cached.

How claude-thermos Works

claude-thermos functions as a local reverse proxy. It intercepts /v1/messages traffic, groups it into sessions and lineages, and identifies when a main lineage is at risk of expiring while a subagent is active. The tool then automatically warms the cache in the background to prevent expiration. Users run Claude Code through claude-thermos, and existing Claude arguments pass through directly. It requires Python 3.11+ and the Claude CLI.