🌡️ Claude-thermos: Stop the "Cache Cold-Start" Tax

Claude-thermos is a utility designed to prevent your Claude Code prompt cache from expiring during long-running operations, ensuring you don't pay a premium to rebuild your conversation history.

---

📉 The Problem: The 5-Minute Expiry

In Claude Code, the prompt cache is a lifesaver—it allows the model to read previous conversation history at a fraction of the cost. However, this cache has a 5-minute Time-To-Live (TTL).

The "Subagent Trap"

When your primary agent delegates a task to a subagent, the following happens:

1. The subagent uses a different system prompt and toolset, creating a separate cache prefix.
2. While the subagent is working, the main agent's cache sits idle.
3. If the subagent takes longer than 5 minutes, the main agent's cache silently expires.
4. When the subagent returns, the main agent must re-encode the entire history.

The Financial Hit: Instead of a cheap cache read, you are charged the write rate (1.25x) for the entire prefix. In sessions with heavy subagent usage, this "re-encoding tax" can account for roughly 10% 22% of your total bill.

Visualizing the Cache Decay

---

🚀 The Solution: claude-thermos

claude-thermos acts as a lightweight local reverse proxy. It intercepts traffic to the Anthropic API (by redirecting ANTHROPIC_BASE_URL to a local port) and monitors "lineages"—groups of requests sharing the same model, tools, and system text.

How it Works

When the proxy detects that the main agent is idle while a subagent is active, it triggers a "warm request":

• It sends the main agent's last request to the API.
• It sets max_tokens: 1 and disables streaming.
• The resulting token is discarded, but the prefill refreshes the cache TTL.

Installation & Usage

To get started, ensure you have the following:

• Python 3.11 or higher
• claude CLI installed and available on your PATH

claude $\rightarrow$ Use uvx to run the warmer:

# Standard run
uvx claude-thermos

# Run with specific prompts (arguments are passed directly to Claude)
uvx claude-thermos -p "fix the bug in the auth module"

Note: To temporarily bypass the warmer without changing your command, set the environment variable CLAUDE_WARMER_DISABLE=1.

---

⚙️ Tuning & Configuration

All settings are optional. You can adjust the behavior using these flags:

---

💰 Calculating Your Savings

The tool tracks every event in ~/.claude-thermos/logs/[session_id]/.

• events.jsonl: A detailed, append-only stream of every request and warming decision.
• summary.json: A final rollup of the session's financial impact.

The Math of Warming

The cost-benefit analysis is based on the difference between a cache read and a full write.

$\text{Net Savings} = (1.25 \times \text{rewrite\_avoided\_tokens}) - (0.1 \times \text{cache\_read\_total})$

Example Scenario: If your summary.json shows a net_savings of $1,200,000$ tokens and your model costs \3$per$1\text{M}$ input tokens:

$\text{Dollars Saved} \approx 1,200,000 \times \frac{\$3}{1,000,000} = \$3.60$

Summary Field Definitions

• warms_fired: Total warm requests sent.
• cache_read_total: Tokens processed during warming.
• episodes: Instances where a subagent was active and a resume was successful.
• rewrite_avoided_tokens: The volume of tokens that would have been re-encoded.
• warm_cost: The cost of warming ($0.1 \times$ read tokens).
• rewrite_avoided_cost: The cost prevented ($1.25 \times$ avoided tokens).