Claude-thermos: Keeping Claude Code Sessions Warm

Claude-thermos: Keeping Claude Code Sessions Warm

Claude‑thermos keeps Claude Code sessions warm

Claude‑thermos is a wrapper that prevents the main agent’s prompt cache from expiring while a subagent runs longer than five minutes, saving the costly re‑encode of the conversation history.

Why the cache expires and what it costs

The main conclusion is that Claude Code’s prompt cache has a five‑minute TTL, and when the main agent is idle because it is blocked on a subagent, the cache ages and is dropped, forcing a full rewrite at the write rate.

"Claude Code's prompt cache uses a 5‑minute TTL. Every turn, your whole conversation history is served from cache at 0.1x the input price instead of being re‑sent at full price, as long as the cache stays alive."\nIf the cache expires, the next turn re‑encodes the entire history at 1.25x the input price. Across roughly 185 local sessions these rewrites accounted for about 22% of the total bill, money spent re‑encoding content that was already cached moments earlier.

How claude‑thermos works

The tool works by running Claude Code behind a tiny local reverse proxy that watches the API traffic, detects when the main lineage is idle while a subagent is active, and issues cheap warm requests to refresh the cache.

  1. Observe. The proxy groups requests into sessions and lineages; the first tool‑bearing lineage is the main agent.\n2. Detect the danger window. When the main lineage goes idle and a subagent is actively running, the main prefix is at risk of expiring.\n3. Warm. On an interval under the five‑minute TTL it replays the main agent's last real request as a warm request with max_tokens: 1 and no streaming; the single token is discarded but the prefill refreshes the full cached prefix.\n4. Result. When the subagent finishes, the main agent's cache is still warm, so it pays a cheap read instead of a full rewrite.\nEach warm costs a cache read (0.1×); each rewrite it prevents would have cost a write (1.25×) on a much larger prefix, making the trade heavily favorable.

Usage and configuration

To use claude‑thermos you run Claude Code through it with uvx; no other changes are required.

uvx claude-thermos                     # instead of: claude
uvx claude-thermos -p "fix the bug"    # any claude args pass straight through

It requires Python 3.11+ and the claude CLI on your PATH. Warming runs automatically in the background. To disable it for a single run set CLAUDE_WARMER_DISABLE=1. Optional tuning flags are:

  • --idle (default 270 s) – seconds the main agent must be idle before warming starts
  • --interval (default 270 s) – seconds between warming cycles
  • --max-cycles (default 4) – max warms per idle episode (auto for unlimited)
  • --subagent-window (default 540 s) – seconds a subagent counts as "still active"

Event logs and savings calculation

Each session writes structured logs to ~/.claude-thermos/logs/<session_id>/. The key takeaway is that the summary file lets you see exactly how much you saved.

  • events.jsonl – append‑only stream of every request/response and warming decision.\n- summary.json – rollup totals written when the session ends.\nFields in summary.json:\n * warms_fired – number of warm requests sent\n * cache_read_total – tokens read back by those warms\n * episodes – idle‑with‑subagent episodes that ended in a successful resume (a rewrite actually avoided)\n * rewrite_avoided_tokens – tokens that would have been re‑written, summed across episodes\n * warm_cost – 0.1 × cache_read_total\n * rewrite_avoided_cost – 1.25 × rewrite_avoided_tokens\n * net_savings – rewrite_avoided_cost − warm_cost\nAll cost figures are in base‑input‑token units. To convert to dollars multiply net_savings by your model’s price per input token. For example, at an input price of $3 / 1M tokens, a net_savings of 1 200 000 yields about $3.60 saved.

Community reaction

Comments on the Hacker News post highlighted both enthusiasm and skepticism.

"This is just making it more expensive for everyone else, right? How Claude handles its sessions is none of my business." – @SwellJoe\n> "I’ve directly inspected calls for pro/Max plans and as of today they have 1hr cache expiries. This has definitely degraded to 5 min in the past but that’s the behavior today." – @unholiness\n> "Feels like will be shut down real quick." – @alukin\n> "Is the 5‑minute expiration correct? I thought it was more like ~1 hour." – @jonas21\n> "How will this not lead to tragedy of the commons?" – @cosmotic\n> "Glad this exists. It will force anthropic to fix their flawed cache mechanism." – @ATMLOTTOBEER\n> "Don’t we pay for cache input though?" – @razodactyl\n> "This is a good idea if it could manage it in an acceptable way… maybe it could just be a few cache delays per day or something." – @j45\n> "I assumed …"hot pockets" … Hearing one byte refreshes the whole thing is huge! 5 min is wayy too slow…" – @purpleidea\n> "They should increase the cache to 10 minutes. 5 is just too low…" – @jaimehrubiks\n> "I thought the cache length was 1 hour, not 5 minutes?" – @2001zhaozhao\n> "FYI, on Pro and Max plans caching lasts for one hour, not five minutes, unless you’re currently using Extra Usage." – @Wowfunhappy\nOverall, the discussion shows uncertainty about the actual TTL for different plans, concerns about fairness and potential abuse, and optimism that the tool could push Anthropic to improve its caching.

Bottom line

The bottom line is that claude‑thermos offers a low‑overhead way to avoid unnecessary cache rewrites in Claude Code sessions, with measurable savings reported by the author and a simple setup that integrates transparently into existing workflows.

Sources