The claude-thermos tool combats the issue of Claude Code's prompt cache expiring during long sessions, particularly when subagents are involved. When a main agent waits over 5 minutes for a subagent, its prompt cache expires. The next interaction then forces a full re-encoding of the conversation at a higher write rate, instead of a cheaper read from the cache. This can account for approximately 20% of a user's Claude Code bill.

claude-thermos operates as a local reverse proxy. It monitors `/v1/messages` traffic, identifying main agents and subagents. When the main agent becomes idle and a subagent is running, claude-thermos proactively sends small 'warm' requests to the API. These requests, while discarded, refresh the main agent's cache before it expires.

This process ensures that when the subagent completes its task, the main agent's cache is still active. Consequently, subsequent interactions are read cheaply from the cache, avoiding the costly re-encoding at the 1.25x write rate. The tool requires Python 3.11+ and the Claude CLI. Optional tuning parameters allow customization of idle timeouts and warming intervals.