cache-keepalive

claude-code-cache-keepalive

⚠️ EXPERIMENTAL — READ THIS BEFORE INSTALLING

This project is an experiment. It works by exploiting a currently-documented (but not contractually guaranteed) property of Anthropic's prompt cache: that cache reads refresh the 5-minute TTL. The economics assume you understand how it works. Used wrongly, this plugin will cost you more, not less.

Before you install, you need to understand at minimum:

• It is only useful on API-key / token-metered billing. On Pro/Max subscription plans, your quota is gated by request count, not token cost — every keepalive turn eats your 5-hour quota. On subscriptions, this plugin makes things worse. Disable it.
• Every keepalive turn is a real turn. It reads the cached prefix and produces a short reply. If your keepalive_message derails Claude into running tools or generating long output, the "cheap ping" stops being cheap.
• The whole trick depends on one invariant (cache reads refresh the TTL). Anthropic can change that without notice — the same way they silently changed the default TTL from 1h to 5m in March 2026 (claude-code#46829). If they do, this plugin will quietly stop saving money and may start costing money.
• You must watch for community updates. Follow the linked issues and the CHANGELOG of this repo. When the community reports a behavior change on Anthropic's side, re-tune your interval_seconds / max_loops_per_turn or disable the plugin entirely. A plugin you installed six months ago and forgot about is the exact scenario where this kind of trick silently turns against you.

Read the Theoretical basis, The economics, and Caveats and warnings sections in full before enabling this. If any of those sections don't make sense to you yet, that's the signal that you are not yet ready to install this plugin. By installing, you accept that you have read and understood the mechanism and are responsible for monitoring its ongoing economics yourself.

---

A Claude Code plugin that keeps the prompt cache warm across idle thinking pauses. It uses the Stop hook's decision: "block" mechanism to inject a tiny keepalive turn just before the 5-minute cache TTL expires. Cache reads cost ~12.5x less than cache writes, so this saves real money on long sessions with idle gaps.

Why this exists. In March 2026 Anthropic silently lowered Claude Code's default prompt-cache TTL from 1 hour to 5 minutes. Users with normal 5+ minute thinking pauses started getting billed for full cache rewrites on every turn. See anthropics/claude-code#46829 for the original issue and the ~$2.5k of excess billing one user traced to the change. This plugin is a workaround.

---

Install

This repo ships as both a Claude Code plugin and a single-plugin marketplace. Inside Claude Code:

/plugin marketplace add yujiachen-y/claude-code-cache-keepalive
/plugin install cache-keepalive@claude-cache-tools

That's it. No daemon, no tmux, no Python, no curl, no API key.

To verify the plugin is active:

/plugin

and look for cache-keepalive in the enabled list. You can also tail the hook log:

tail -f ~/.claude/cache-keepalive/cache-keepalive.log

---

How it works

When Claude finishes a turn, Claude Code fires the Stop hook. This plugin's Stop hook script sleeps for interval_seconds (default 240s, safely under the 300s TTL) and then writes this JSON to stdout:

{"decision":"block","reason":"got it, i need some time to think about the next move"}

Claude Code treats that as "the user sent a new instruction" and asks Claude to respond. The response reads the cached prompt prefix — and cache reads refresh the 5-minute TTL. Claude replies with one short line, Stop fires again, the loop continues.