Cache Bell

Cache Bell manages the prompt cache and the context of long Claude Code sessions. Once the context passes a size you choose, 200K tokens by default, Claude compacts after it finishes a piece of work and you get 30 seconds to cancel. While you are away, it renews the cache before it expires or compacts while it is still warm, so your first message after a break does not send the whole context again uncached.

idle-compact compacts once at minute 50 and cache-keeper keeps big chats warm with pings. Cache Bell asks you first, can do either, and adds compaction by size.

What it does

• Compaction by size. Past compactLevelK, Claude is asked to compact at the next good point and requests it when its work is done. compactOnRequest decides what the request does: compact when the countdown ends (confirm, the default), wait for your answer (wait), compact at once (auto) or refuse (off). /bell set 300K gives one session its own level.
• A note for afterwards. With its request Claude can leave itself a note on what comes next. After the compaction the plugin sends the note back as a prompt and the session carries on without you, up to five compactions in a row (compactNotesInRow).
• Context size for Claude. From half the window on, Claude gets a one-line notice with the context’s size, again at every further 5% and at 85, 90 and 95%. You do not see it.
• A question before the cache expires. A band above the prompt asks what to do: type 1 to compact now, 2 to renew, 3 to let it expire, then Enter, or click a choice. The digit is not sent to the model. With no answer, the plugin acts on its own.
• Countdown in the status line. It shows whether the cache is warm or cold, with a countdown once 15 minutes or fewer are left (display, displayBelowMinutes).
• A log of compactions. /bell log lists the plugin’s compactions, your /compact and Claude Code’s automatic ones, with the size before and after, the cause and who decided.
• Summary instructions. compactInstructions works like the text after /compact, for the plugin’s own compactions only, with {time} and {idle} filled in.

Install

Needs Claude Code 2.1.288 or later.

claude plugin marketplace add hollerbell/cache-bell
claude plugin install cache-bell@cache-bell

Open a new session, or run /reload-plugins in an open one. /bell status tells you what the plugin sees and what it will do next; /bell demo 30 shows the question for 30 seconds and sends nothing. The options are the cache-bell.* rows in /config. Claude Code does not update this marketplace on its own unless you turn on auto-update for it under /plugin.

How it works

The prompt cache lives 5 minutes or 1 hour, counted from the last request sent to the API, not from the end of the turn. Cache Bell learns which one the API granted from the usage figures at the end of the session’s transcript, and until a response shows it, the plugin does not ask, renew or compact on its own. On an hour-long cache the question appears at minute 35 and the plugin acts at minute 50, five minutes before the last safe moment; on a five-minute cache, at 3:30 and 4:00.

While you are away. With the default profile, bellcompact, it asks first and, with no answer, renews the cache twice. A renewal is a side request (model.fork) whose one-line prompt (idleRenewPrompt) asks the model to reply “ok”: it reads the whole context from the cache, which renews it, and leaves nothing in the transcript. On an hour-long cache the plugin then asks again with Compact selected, tells the session in a short turn of its own that a compaction is coming so it can save its work, and compacts, about two and a half idle hours after your last request. On a five-minute cache it lets the cache expire after the renewals, about 13 minutes after your last request; idleCompact set to on compacts there too, and off never compacts.

That is at most five requests per idle period without your answer on an hour-long cache (two renewals, one retry of a renewal that got no response, the announcement and the compaction) and three on a five-minute one. Only your own message starts the count over. Under 80,000 tokens of context (idleMinContextK) the plugin only shows the countdown.

What it costs. Renewals, the announcement, compactions and the notes sent after them all count against your plan’s limits or are billed to your API key. Skipping the renewals has its own price: after a break, your first message writes the whole context to the cache again, at the full input price plus the write surcharge. In the author’s one measurement, an hour-long cache renewed at minute 50 let a message at minute 63 read the whole context, 42,571 tokens, from the cache and write only 374. A compaction is one summary request, and whatever the summary leaves out is gone from the context.

Compaction by size. After each tool result in the main conversation, a tool.call hook lets the tool run and appends a line for Claude to the result: the context’s size and, past the level, that you want a compaction at the next good point, with nothing of the conversation in it. A bundled skill tells Claude when to ask, and it asks through the compact tool the plugin registers (mcp__cache-bell__compact). The countdown starts when the turn ends: 30 seconds, the time Claude names (10 to 600), or three seconds when you asked for the compaction yourself. The plugin’s compactions wait while you type (a key in the last minute) or a subagent runs, but never past the cache. While it looks after an idle session, it also holds back Claude Code’s own idle compaction, which otherwise runs above roughly 200K tokens.

The hour-long cache. The README says that since Claude Code 2.1.293 an interactive session gets the five-minute cache unless it asks for the hour (Anthropic’s docs give subscribers on their plan the hour by default). The first-run notice asks what you usually do after Claude replies. Only if you answer that you come back within the hour, or run /bell hour on, does the plugin set CLAUDE_CODE_PROMPT_CACHE_TTL=1h in the environment of the running Claude Code process, never in your shell or settings, and only at a moment the cache is cold anyway. On the API, writing an hour-long cache costs twice the base input price, against 1.25 times for five minutes. Two more tool.call hooks, on Bash and PowerShell, take the variable out while a shell command of the main conversation runs with no subagent active, so a claude -p started there does not ask for the hour. A TTL you set yourself is never touched.

What it reads and runs. Of a transcript above 4 MiB it reads only the end, at most 1 MiB, by starting tail through process.run (on Windows, PowerShell by its full path). It looks at usage figures, not at what was said, and keeps nothing. It sees each message as it is sent, to compare it with the digits of an open question, and keeps none. It notes when you last typed in the prompt box, not what. Its hooks on tool calls read the tool’s name, whether a subagent made the call and the context’s size, never what the tool was given. It makes no network connections of its own: its requests go to the model through Claude Code, like your messages.

What it keeps. A JSON file in the plugin store under Claude Code’s configuration directory holds whether you saw the first-run notice, your answer about the hour, and the last 200 compactions: time, sizes, cause, the first eight characters of the session id and Claude’s one-sentence reason, up to 200 characters. It writes nothing to settings.json.

Limitations

• The questions show only in the terminal. In a session you follow over Remote Control, from the desktop app or a phone, nobody sees them, so the countdown ends as if unanswered. With the defaults that ends in a compaction, which cannot be undone. The author’s advice: set cache-bell.compactOnRequest to wait and cache-bell.idleCompact to off.
• Experimental. Version 0.3.11 does not support the desktop app’s Code tab or the SDK, and does nothing in claude -p. The author tested it in the terminal on Windows and macOS; Linux is untested.
• A lone digit is an answer. While a question is open, a message that is exactly one of its digits answers the question and never reaches Claude, even if Claude has just asked you to pick 1 or 2. Write more than the digit.
• Background shells do not count. A compaction waits for your typing and for subagents, not for a background shell command such as a dev server.
• No TTL, no action. Where the transcript cannot be read, the session keeps none, or a provider’s responses do not report the cache, the plugin only says so. Setting cacheTtl to 5m or 1h gets around it.