Claude Code's main agent waits six minutes for a sub-agent. When the sub-agent returns and the main agent resumes, nothing breaks on screen — but the bill may suddenly bulge.
The reason: the Prompt Cache expired.
Anthropic's default cache TTL is 5 minutes. On a cache hit, reads cost 0.1x the base input price; writing a fresh 5-minute cache costs 1.25x. Each hit refreshes the TTL. The problem arises 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 idles past 5 minutes, resuming may require re-encoding the entire long context. [1]
The open-source tool claude-thermos targets exactly this gap.
It runs Claude Code behind a local reverse proxy via ANTHROPIC_BASE_URL, so requests 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 cache prefix stays byte-identical, max_tokens is squeezed down to 1, and streaming is disabled. The single generated token is discarded — the goal is only to reset the TTL with one cheap cache read. [2]
Default parameters are conservative:
- Warmup starts after 270 seconds of main-agent idle time;
- At most one refresh every 270 seconds;
- Up to 4 warmup cycles per idle period;
- Sub-agents count as "still working" only if active within 540 seconds;
- Daemon mode listens on
127.0.0.1:8787by default, with sessions cleaned up after 3600 seconds of inactivity.
claude CLI, then swap your daily command for uvx claude-thermos. For IDE or multi-terminal sharing, start claude-thermos serve. [2]How solid is the savings evidence?
The author tracked roughly 185 local sessions and claims cache rebuilds accounted for about 22% of the total bill, with individual 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, few sub-agents, and shorter contexts yield much smaller gains. Frequent warmups aren't free either: each one still pays 0.1x cache read plus a tiny amount of output tokens.
A more rigorous approach is to check the three numbers the project records: tokens read during warmups, rewrite tokens avoided, and the net savings after weighting by 0.1 vs 1.25. It writes events to local ~/.claude-thermos/logs/, including warmup triggers, cache reads, and estimated savings — teams can A/B test a dozen of their own long sessions instead of copying the "22% saved" figure.
Two more caveats
First, this is a third-party local proxy. It must see and forward Claude requests, which means one more link in the supply chain and one more high-privilege local process. In sensitive code environments, pin the version, audit the source, restrict loopback access, and confirm logs don't contain request bodies.
Second, Anthropic natively offers a 1-hour TTL at a 2x write price. Teams whose sub-agents routinely run ten-plus minutes should directly compare "1-hour cache" against "5-minute cache + thermos warmup" bills. 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 a money-saving trick. It moves AI coding's cost problem from "which model to pick" to "how to manage cache lifecycle." As long-horizon agents proliferate, this kind of unglamorous runtime engineering becomes increasingly valuable.
Sources
1. Anthropic Prompt Caching official documentation
2. claude-thermos GitHub repository and README