claude-thermos

claude-thermos is an open-source Python tool by Iaroslav Zeigerman that wraps Claude Code behind a lightweight local reverse proxy to prevent prompt cache expiration during multi-agent sessions. It targets a specific and measurable cost problem: when a main Claude agent waits on a subagent for more than 5 minutes, the main agent's prompt cache silently expires, forcing a full re-encode at the write rate (1.25x) instead of the cheap cache read rate (0.1x). The README states that across roughly 185 local sessions, these rebuilds accounted for about 22% of total API spend.

What It Is

claude-thermos is a CLI wrapper and optional daemon that intercepts Anthropic API traffic on a loopback port, monitors session activity, and periodically replays the main agent's last real request with max_tokens: 1 to refresh the prompt cache prefix before it expires. It is written in Python, licensed under MIT, and distributed via uvx (no install required). The core product is the open-source tool itself — there is no hosted service or SaaS component.

How the Cache Warming Works

The proxy observes /v1/messages traffic and groups requests into sessions and lineages — one cache prefix per unique combination of model, tool set, and system text. The first tool-bearing lineage is treated as the main agent; subsequent ones are subagents. When the main lineage goes idle while a subagent is active, the tool enters a "danger window":

• On a configurable interval (default: 270 seconds, under the 5-minute TTL), it replays the main agent's last request as a warm request with max_tokens: 1 and no streaming.
• The single output token is discarded; the goal is the prefill, which reads and refreshes the cached prefix.
• Warm requests go directly to the Anthropic API, never back through the proxy, so they cannot interfere with real traffic.
• Each warm costs a cache read (0.1x); each prevented rewrite would have cost a write (1.25x) on a much larger prefix.

Deployment Modes

claude-thermos supports two usage patterns:

• Launcher mode (uvx claude-thermos): wraps a single claude process, warming only that session. Any Claude arguments pass straight through.
• Daemon mode (claude-thermos serve): runs a standalone proxy on a fixed loopback port (default: 8787). Any client that sets ANTHROPIC_BASE_URL=http://127.0.0.1:8787 — including the VSCode/Claude Code extension — routes through the shared warmer. A single daemon serves all clients on the machine and evicts sessions idle longer than --session-ttl (default: 3600s).

Tunable flags include --idle, --interval, --max-cycles, and --subagent-window, all with sensible defaults.

Event Logs and Savings Tracking

Every session writes structured logs to ~/.claude-thermos/logs/<session_id>/:

• events.jsonl: append-only stream of every request/response token count and warming decision (warm_fired, warm_result, cap_reached, resume_detected, etc.)
• summary.json: rollup totals including warms_fired, cache_read_total, rewrite_avoided_tokens, warm_cost, rewrite_avoided_cost, and net_savings in base-input-token units.

To convert net_savings to dollars, multiply by the model's input token price. The README gives an example: a net_savings of 1,200,000 at $3/1M tokens equals approximately $3.60 saved per session.

Current Status

The repository was created in July 2026 and last pushed on July 24, 2026, with 161 stars and 7 forks at time of indexing. It requires Python 3.11+ and the claude CLI on the system PATH. The project is actively maintained under the MIT license by Iaroslav Zeigerman.