claude-thermos: Keeping the 5-Minute Prompt Cache Alive — How the Math Works for Long Claude Code Sessions

Your Claude Code main agent waits six minutes for a subagent to finish. The subagent returns, the main agent resumes — nothing looks broken on screen, but your bill may have suddenly grown a chunk.

The cause: the Prompt Cache expired.

Anthropic's default cache TTL is 5 minutes. On a cache hit, reads cost 0.1x the base input price; a fresh 5-minute cache write costs 1.25x. Each hit refreshes the TTL. The problem shows up in multi-agent workflows: subagents have different system prompts, tool sets, and context prefixes, so their requests don't refresh the main agent's cache. If the main agent idles more than 5 minutes, resuming can mean re-encoding the entire long context at full price. [1]

The open-source tool claude-thermos targets exactly this gap.

It places Claude Code behind a local reverse proxy via ANTHROPIC_BASE_URL, so requests pass through loopback first. The proxy distinguishes lineages by "model + tool set + system text," identifying which traffic is the main agent and which are subagents. When the main agent goes idle while subagents are still running, the tool replays the main agent's last real request: the cache prefix stays identical, max_tokens is squeezed to 1, and streaming is disabled. The single generated token is discarded — the point is just to push the TTL back with one cheap cache read. [2]

Default parameters are conservative:

• Warmup begins after 270 seconds of main-agent idle;
• At most one refresh per 270 seconds;
• Maximum 4 warmup cycles per idle period;
• A subagent counts as active only if it showed activity within 540 seconds;
• Daemon mode listens on 127.0.0.1:8787 by default, cleaning up sessions idle for 3600 seconds.

The install bar is low: Python 3.11+, an existing claude CLI, then swap your usual command for uvx claude-thermos. For IDE or multi-terminal sharing, run claude-thermos serve. [2]

How Solid Is the Savings Evidence?

The author analyzed roughly 185 local sessions and claims cache rebuilds accounted for about 22% of total costs, with single rewrites often landing between 200k and 500k tokens. Treat this as the project author's workload sample, not a figure you can extrapolate to every team. Short sessions, few subagents, and shorter contexts will see much smaller gains. Frequent warmups aren't free either: each still costs a 0.1x cache read plus a tiny number of output tokens.

The sounder approach is to check the three numbers the tool itself records: how many tokens warmups read, how many rewrites were avoided, and the net savings after weighting by 0.1 vs 1.25. It writes events to ~/.claude-thermos/logs/, including warmup triggers, cache read volumes, and estimated savings — teams can run an A/B on a dozen of their own long sessions instead of copying the "saves 22%" headline.

Two More Boundaries

First, this is a third-party local proxy. It must see and forward Claude requests, which adds a supply-chain link and a high-privilege local process. In sensitive code environments, pin versions, audit the source, restrict loopback access, and confirm logs don't contain request bodies.

Second, Anthropic natively offers a 1-hour TTL with a write price of 2x base input. Teams whose subagents routinely run 10+ minutes can directly compare "1-hour cache" vs "5-minute cache + thermos warmup." The latter is more flexible; the former avoids an extra proxy layer. There's no universal answer.

The most interesting thing about claude-thermos isn't the money-saving trick itself. It moves the AI coding cost question from "which model to pick" to "how to manage cache lifecycles." As long-horizon agents become widespread, this kind of unglamorous runtime engineering becomes increasingly valuable.

Sources

1. Anthropic Prompt Caching documentation 2. claude-thermos GitHub repository and README