cache-keepalive

cache-keepalive keeps Claude Code’s prompt cache warm while background tasks run. When Claude ends a turn with a task still going, the mod sends a one-line ping every 50 minutes so the cache does not expire before the task reports back, and it stops on its own once the pings have cost as much as the rewrite they were meant to avoid.

The stakes: if the cache has expired when the task’s notification arrives, the next request writes the whole context into the cache again at twice the input price. A ping reads the context from the cache instead, at 0.025 to 0.1 times the input price depending on the model. cache-keeper keeps a chat warm on request for a set number of hours, next to a cold-send guard and a board of chats; cache-keepalive arms itself only when background work is pending and caps its own spending.

Install

Needs Claude Code 2.1.287 or later.

claude plugin marketplace add RichardJSun/claude-code-mods
claude plugin install cache-keepalive@richardjsun-mods

There is nothing to start: the mod arms itself when a turn ends with background tasks running. /keepalive sends a ping right away, which costs the same as the others, and reports whether it hit the cache and how much of the budget is spent. The status line shows armed, warm or why it stopped.

How it works

When a turn ends (classic.Stop) with background tasks still running, the mod reads the session’s context size and rate limits, sets a budget equal to the cost of rewriting that context into the cache, and starts a 50-minute timer.

Each ping is a model.fork: a real model request on a copy of the conversation that asks for a one-word reply. It reads the full context from the cache, which keeps the cache alive, and the mod uses the reply only for its token counts. Nothing is added to your conversation.

The mod prices each ping in input-token equivalents: cache reads at 0.025 times input on Fable, 0.05 on Opus 5.5 and 0.1 on other models, cache writes at 2 and output at 5. On Opus 5.5 a ping costs about 2.5% of a rewrite, so the budget lasts roughly 40 pings, some 33 hours of waiting. At 0.1 it lasts about 20 pings, some 16 hours. The pings are ordinary usage: on a subscription they count against your plan’s limits, on the API they are billed.

The pings stop when:

• a new turn starts, as it does when the task’s notification arrives;
• a ping reads 90% or less of the context from the cache, a miss;
• the pings have spent the budget;
• the 5-hour or 7-day rate-limit window reaches 100% during the wait. The mod does not arm while one of them is already there.

Ping results go to the debug log. Apart from the pings and compactions, which are model requests, the mod makes no network calls.

The compactOnCap option, off by default, compacts the conversation when the budget runs out, while the cache is still warm, so the next request caches a summary instead of the full context. It does so only when the compaction plus caching the summary costs less than re-caching everything, and it asks the compaction to keep the background tasks’ IDs, output paths and next steps. It saves the cost and summary size of each compaction in its local store to decide the next one. Compaction loses context detail, which is why it is off by default.

Limitations

• It assumes the 1-hour cache and cannot read the cache lifetime. It infers the 5-minute one only from overage, which switches a session to it. If the session is on the 5-minute cache anyway, the first ping finds it cold, pays for the full rewrite itself, and the mod stops.
• It ignores limits that apply to a single model, such as Fable’s weekly limit, because mods cannot read them. If one runs out, the first ping misses and the mod stops.
• It learns the rate limits only from this session’s own responses, so overage that other sessions cause during the wait can go unnoticed.