# claude-thermos

> A local reverse proxy that keeps your Claude Code prompt cache warm during long subagent runs, preventing expensive cache rebuilds and reducing API costs.

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.

## Features
- Keeps Claude Code prompt cache warm during subagent runs
- Local reverse proxy intercepting Anthropic API traffic
- Launcher mode wraps a single claude process
- Daemon mode serves multiple clients and terminals on one machine
- VSCode/Claude Code extension support via ANTHROPIC_BASE_URL
- Configurable idle, interval, max-cycles, and subagent-window flags
- Structured event logs (events.jsonl) per session
- Session summary with net savings calculation (summary.json)
- Warm requests use max_tokens:1 to minimize cost
- Session eviction via configurable --session-ttl
- CLAUDE_THERMOS_DISABLE=1 env var to skip warming for a run
- Requires no install via uvx

## Integrations
Claude Code CLI, Anthropic API, VSCode Claude Code extension, uvx / uv

## Platforms
MACOS, API, VSC_EXTENSION, CLI

## Pricing
Open Source

## Links
- Website: https://github.com/izeigerman/claude-thermos
- Repository: https://github.com/izeigerman/claude-thermos
- EveryDev.ai: https://www.everydev.ai/tools/claude-thermos