Claude Code's main agent waits six minutes for a sub-agent to finish. The sub-agent returns, the main agent continues — nothing looks broken on screen, but the bill may suddenly grow a lump.
The reason: the prompt cache expired.
The problem: 5-minute cache TTL in multi-agent workflows
Anthropic's default cache TTL is 5 minutes. On a cache hit, reads are billed at 0.1x the base input price; a fresh 5-minute cache write costs 1.25x. Every cache hit refreshes the TTL. The issue 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]
What claude-thermos does
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 which traffic is the main agent and which are 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 pressed down to 1, and streaming is disabled. The single generated token is discarded — the goal is merely one cheap cache read to push the TTL back. [2]
Default parameters are conservative:
- Warm-up starts after the main agent idles for 270 seconds;
- At most one refresh every 270 seconds;
- At most 4 warm-up cycles per idle period;
- Sub-agents count as active only within 540 seconds of activity;
- Daemon mode listens on
127.0.0.1:8787by default, with sessions cleaned up after 3600 seconds idle.
claude CLI, then swap your daily command for uvx claude-thermos. For IDEs or multiple terminals sharing a session, 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 the total bill, with single rewrites often falling between 200k and 500k tokens. Treat this as one project author's workload sample — it does not generalize to all teams. Short sessions, little sub-agent use, and shorter contexts mean much smaller gains. Frequent warm-ups are not free either: each still pays 0.1x cache read plus a tiny amount of output tokens.
A more robust calculation uses the three numbers the project logs: tokens read during warm-ups, tokens of avoided rewrites, and the net savings after weighting both at 0.1x and 1.25x respectively. Events are written to local logs at ~/.claude-thermos/logs/, including warm-up triggers, cache read volumes, and estimated savings. Teams should run their own A/B comparison across a dozen long sessions rather than copying the "22% saved" figure.
Two caveats
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 contain no message bodies.
Second, Anthropic natively offers a 1-hour TTL at a 2x write price. Teams whose sub-agents routinely run 10+ minutes can directly compare "1-hour cache" versus "5-minute cache + thermos warm-ups." The latter is more flexible; the former removes a proxy layer. There is no universal answer.
The most interesting thing about claude-thermos is not that it is a money-saving trick. It moves the cost question of AI coding from "which model to pick" to "how to manage cache lifecycle." As long-horizon agents become more common, this kind of unglamorous runtime engineering becomes more valuable.
References
1. Anthropic Prompt Caching documentation
2. claude-thermos GitHub repository and README