cache-keeper

cache-keeper watches the prompt cache of every Claude Code chat on your machine. It shows how long a chat’s cache stays warm and what the next message costs once it goes cold, keeps a big chat warm on request, and hands a bloated chat off to a fresh one.

The stakes: each request re-reads the whole chat, cheaply from the cache. Once the cache expires, after 5 minutes or an hour idle depending on your setup, the next message writes the whole chat into it again at 1.25 to 2 times the input price, which on a 400k-token chat means a few dollars. cache-tax covers the same moment with a one-time block and keep-warm pings; cache-keeper adds a three-way question, a board of all your chats and a handoff.

What it does

• Line above the prompt. Cache state with minutes left, context size, the price of a rewrite, your 5-hour, weekly and spend limits (yellow at 80%, red at 95%) and the session’s cost. It turns yellow 5 minutes before expiry, and on a big chat a keep warm button appears (hotkey 1).
• /keepwarm [hours|off]. Sends a tiny request shortly before the cache would expire, so the cache is read instead of rewritten. Four hours by default, 24 at most. It switches itself off when a ping writes to the cache instead of reading it, or gets no answer.
• Cold-send guard. When you send into a chat over 150k tokens whose cache has expired, it asks first: Send anyway, Compact first, then send, or Cancel.
• /board. A pane with every local chat: the ones waiting on you first, then working ones, then the ones whose cache cools soonest. Each row shows state, context, cache, cost and running agents. Big chats get a keep-warm button that also works on another chat, within 30 seconds. Toasts tell you when another chat starts waiting on a permission or a question, and when any big chat is 5 minutes from going cold.
• /handoff. Runs the bundled session-handoff skill, saves the result to a file, then offers to /clear the chat and send the handoff as the first prompt of the fresh context. /handoff continue does the second half later.
• /cache. Status and settings: ttl 5|60|auto, guard on|off, big 150k (the size that counts as big), alerts on|off.

Install

Needs Claude Code 2.1.287 or later.

claude plugin marketplace add nateherkai/claude-code-mods
claude plugin install cache-keeper@nateherk-mods

Open a new chat afterwards: the mod loads when a chat starts, and /reload-plugins does not reload it. The line above the prompt appears after the chat’s first request.

How it works

Every main-loop request reports how many tokens it read from the cache and how many it wrote. From that the mod tracks the context size, counts cold restarts and works out whether the chat runs on the 5-minute or the 1-hour cache. Until a request proves otherwise it assumes the 1-hour one; /cache ttl 5 sets it by hand. Context, cost and plan limits come from the engine’s own session usage. The tool hooks read only the tool’s name, to show what a chat is running and whether it is waiting on you, and your first typed prompt, cut to 40 characters, names the chat on the board.

Every 30 seconds each chat writes a heartbeat (name, folder, model, state, context, cache, cost, agents) to the mod’s local store, and heartbeats silent for an hour are deleted. Handoffs are saved under ~/.claude/mods-data/cache-keeper/handoffs/. The mod makes no network calls of its own; the keep-warm pings are model requests, sent only while keep warm is on.

Each ping forks the conversation, reads the whole context from the cache and gets “ok” back. By the mod’s own price table, that is about 8 cents on a 400k-token Opus 5.5 chat, where a rewrite on the 1-hour cache costs $3.20. On the 1-hour cache it pings about 8 minutes before expiry, so the default four hours cost well under a dollar. On the 5-minute cache it pings 90 seconds before expiry, roughly every three and a half minutes, and after about an hour and a half the pings have cost more than the $2 rewrite they avoid. On a subscription plan all of this counts against your limits instead of a bill.

With recording-mode on, chat names on the board and in the toasts are masked, and its strict mode hides the dollar figures.

Limitations

• The line above the prompt and its buttons draw only in the terminal. In the Desktop app’s Code tab, which the author lists as supported, a short footer label carries the cold-cache warning, high plan limits and a ready handoff; use /keepwarm and /handoff there.
• Prices are API list prices written into the mod, dated 2026-09-25 in the code. A model missing from that table is priced as Opus 5.5.
• /clear, /resume and /branch reset the cache state and turn keep warm off.
• The board lists only chats on this machine that loaded the mod.