It directly solves a costly and under‑documented problem in Claude Code: prompt cache expiry when the main agent is blocked on a subagent, saving roughly 22% of total input costs with minimal setup.
Stop paying to rebuild your Claude Code cache. When your main agent waits on a subagent for more than 5 minutes, its prompt cache silently expires, and the next turn re-encodes your entire conversation at the write rate instead of reading it back cheap. On long sessions with many subagents that's roughly 20% of your bill. claude-thermos keeps the cache warm so you never pay that tax.
Run Claude Code exactly as you normally would, but through claude-thermos with uvx:
uvx claude-thermos # instead of: claude
uvx claude-thermos -p "fix the bug" # any claude args pass straight through
Requires Python 3.11+ and the claude CLI on your PATH.
That's it. Warming runs automatically in the background. To disable it for a run without changing the command, set CLAUDE_WARMER_DISABLE=1.
Tuning (all optional):
| Flag | Default | Meaning |
|---|---|---|
--idle | 270 | Seconds the main agent must be idle before warming kicks in |
--interval | 270 | Seconds between warming cycles |
--max-cycles | 4 | Max warms per idle episode (auto for unlimited) |
--subagent-window | 540 | Seconds a subagent counts as "still active" |
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.
The cache expires if more than 5 minutes pass between requests on the same prefix. The dominant trigger for that gap is not you thinking. It's the main agent blocked on a subagent that runs longer than 5 minutes. A subagent has a different system prompt and tool set, so its requests have a different cache prefix and never refresh the main agent's. While the subagent works, the main agent's cached history ages untouched; past 5 minutes it's gone. When the subagent returns, the main agent resumes with a byte-identical, append-only history, and finds its cache missing, forcing a full re-encode at the 1.25x write rate.
By then the history is large, so the re-encode
Keeps your Claude session warm for you
Similar projects matched by category, topics, and programming language.
Clodex is an open-source, local-first agentic IDE that combines persistent AI tasks, code, terminal, browser, Git, models, memory, and governed execution in one Electron workspace, currently in technical preview.
Harness Engineering is a methodology for improving coding agent outputs by carefully crafting the environment around them—providing curated context, tools, and executable constraints that encode an organization’s nonfunctional requirements and cumulative lessons.
Hermes Agent is an open-source, self-improving AI agent with a built-in learning loop that creates skills from experience, runs across platforms, and supports any LLM provider.