Keep Claude Code's prompt cache warm between turns.
English · 简体中文
Cache Warm refreshes Claude Code's prompt cache while you take a break, so the next turn can reuse the cached conversation. It detects the cache lifetime from your session and sends a short keep-alive request before the cache expires. It uses your existing Claude Code connection and needs no separate API key.
Refreshes use tokens and count toward your account's usage or API bill.
Requires Claude Code 2.1.304 or later with mods
enabled, on Linux, macOS, or WSL with the tail command available.
claude plugin marketplace add ZhenHuangLab/claude-cache-warm
claude plugin install zhenhuang@cache-warmStart Claude Code and send a normal message. For a session that is already
open, run /reload-plugins first. Keep the Claude Code process open while you
want warming to continue.
To try the latest release for one session:
claude --plugin-url https://github.com/ZhenHuangLab/claude-cache-warm/releases/latest/download/cache-warm.zip| Detected cache lifetime | Refresh interval |
|---|---|
| 5 minutes | 4 minutes 30 seconds |
| 1 hour | 54 minutes |
Each normal model request starts a new schedule. Successful refreshes extend
it until an idle limit or the ping cap is reached. After a refresh, Claude Code
shows a status such as cache warm (1h): 1 ping.
Each process warms its own main conversation, including teammates running in separate tmux panes. Embedded subagents and teammates within the same process are outside the scope of Claude Code's fork API.
By default, each idle period allows 30 successful refreshes, with a maximum idle duration of 30 hours. The first limit reached stops warming. Each normal model request resets both limits. With uninterrupted refreshes, the ping cap keeps a 5-minute cache available for about 2 hours 20 minutes, or a 1-hour cache for about 28 hours, from the last normal request.
Warming pauses when the cache lifetime is unknown or the cache has expired, and stops after a cache miss. Send another normal message to start a fresh schedule. Model switches and session changes also reset warming.
A refresh reads the cached prompt and generates a short reply. Its cost depends on the prompt size and model. Review prompt caching pricing and your account's usage before leaving long sessions open.
In Claude Code, run:
/plugin configure zhenhuang@cache-warm
Set maxIdleMinutes to the maximum idle duration in minutes. The default is
1800; 0 disables warming. The 30-refresh cap applies at every setting.
For a session loaded with --plugin-url or --plugin-dir, use
zhenhuang@inline as the plugin ID instead.
To disable or remove an installed copy:
claude plugin disable zhenhuang@cache-warm
claude plugin uninstall zhenhuang@cache-warmClaude Code loads the TypeScript source directly. From the repository root:
claude plugin validate --strict .
claude plugin validate --strict .claude-plugin/marketplace.json
claude plugin test .The tests use mocked model requests and a virtual clock.
MIT. See LICENSE.
Thanks to the LINUX DO community for sharing knowledge, support, and feedback, and to Anthropic for Claude Code and its mods API.