claude-thermos: Extending the 5-Minute Prompt Cache, and What Long Claude Code Sessions Really Cost

A Claude Code main agent waits six minutes for a sub-agent. The sub-agent returns, the main agent resumes — nothing visibly breaks, but the bill may suddenly grow.

The cause: the Prompt Cache expired.

Anthropic's default cache TTL is 5 minutes. On a cache hit, reads are billed at 0.1x the base input price; writing a new 5-minute cache costs 1.25x. Every cache hit refreshes the TTL. The problem appears in multi-agent workflows: sub-agents have different system prompts, tool sets, and context prefixes, so their requests do not refresh the main agent's cache. If the main agent is idle for more than 5 minutes, it may have to re-encode the entire long context on resume. [1]

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

It places Claude Code behind a local reverse proxy: via ANTHROPIC_BASE_URL, requests first pass through loopback. The proxy distinguishes lineages by "model + tool set + system text," identifying the main agent versus sub-agents. When the main agent goes idle while sub-agents are still running, the tool replays the main agent's last real request: the cached prefix stays byte-identical, max_tokens is set to 1, and streaming is disabled. The single generated token is discarded — the point is only to use a cheap cache read to push the TTL back.

Default parameters are conservative:

• Warm-up begins after the main agent is idle for 270 seconds;
• At most one refresh every 270 seconds;
• A maximum of 4 warm-up cycles per idle period;
• Sub-agents count as active only if they showed activity within the last 540 seconds;
• Daemon mode listens on 127.0.0.1:8787 by default, with sessions cleaned up after 3600 seconds of inactivity.

Installation is lightweight: Python 3.11+, an existing claude CLI, and replacing your daily command with uvx claude-thermos. For IDE or multi-terminal setups, start claude-thermos serve.

How Solid Is the Savings Evidence?

The author analyzed roughly 185 local sessions and claims cache rebuilds accounted for about 22% of total spend, with single rewrites often landing between 200k and 500k tokens. Treat this as one project author's workload sample — not something to extrapolate to every team. Short sessions, fewer sub-agents, and shorter contexts will see much smaller gains. Frequent warming isn't free either: each refresh still pays 0.1x cache read plus a tiny amount of output tokens.

A more reliable approach is to look at three numbers the project logs itself: tokens read during warm-ups, tokens of avoided rewrites, and the net savings after weighting by 0.1 vs 1.25. It writes events to ~/.claude-thermos/logs/, including warm-up triggers, cache read volumes, and estimated savings, so teams can A/B test with a dozen of their own long sessions instead of copying the "22% savings" figure.

Two Boundaries to Keep in Mind

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

Second, Anthropic natively offers a 1-hour TTL at a 2x write cost. Teams whose sub-agents routinely run 10+ minutes should directly compare "1-hour cache" versus "5-minute cache + thermos warming." The latter is more flexible; the former avoids an extra proxy layer. There is no universal answer.

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

References

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