cache-tax

cache-tax is a Claude Code mod that keeps your prompt cache warm while you step away, and stops your first message once if you come back to a cold cache anyway, with the price of sending it. Claude Code’s main cache expires after an hour of silence. The next message then re-writes the whole context at the cache-write rate: about $4 for a 200,000-token session on Fable 5.1, against five cents for the same turn on a warm cache.

At a glance

• What it does: /keepwarm pings the cache through a break you choose, and a guard drops a cold send once with its estimated cost.
• Where you see it: a row above the prompt while keepwarm is armed, in the terminal and in the Code tab of Claude Desktop.
• Tokens and network: the guard is free. Each ping is a real model request that costs tokens, and the only thing the mod sends.
• Who it is for: sessions of 50,000 tokens and up that you leave and come back to, on a one-hour cache.

Install

Needs Claude Code 2.1.287 or later, a one-hour prompt cache and Claude Code left running during the break.

claude plugin marketplace add karanb192/claude-code-mods
claude plugin install cache-tax@claude-code-mods

Restart Claude Code or run /reload-plugins. The guard is on from the start; run /keepwarm in a warm session before a break. The marketplace is still the author’s claude-code-mods, whose entry now points at the karanb192/cache-tax repository. To update an existing install, run claude plugin update cache-tax@claude-code-mods and restart.

Check your cache lifetime first. Included subscription usage gets the one-hour cache by default. API-key, usage-credit and cloud-provider sessions default to five minutes, which a 50-minute ping cannot protect: set promptCacheTtl to "1h", as Claude Code’s prompt caching docs describe.

“Host key verification failed” on install comes from Claude Code cloning GitHub over SSH with strict host-key checking, not from the mod. Add GitHub’s published host key to known_hosts, or do what a user did in issue #15 and send GitHub URLs over HTTPS, which changes your global git config:

git config --global url."https://github.com/".insteadOf "git@github.com:"

Already running the hook version from karanb192/claude-code-hooks? It warns by default and has a status-line countdown, but no keepwarm. Keep one of the two: with both, every cold send is stopped twice, and the mod tells you so at session start.

Commands

• /keepwarm: keep the cache warm for six hours.
• /keepwarm 90m: a window of your own, such as 2h30m or 48h.
• /keepwarm always: keep every session warm until six hours after its last turn, remembered across sessions.
• /keepwarm status: the window, the next ping and the last readback.
• /keepwarm off: stop, forget the window and turn always off.
• /keepwarm 6h every 2m: a shorter ping period for testing, 1 to 59 minutes, forgotten after the window.
• /cache-tax: the card, with the cold price, warming window, guard mode, break-even and this session’s cold writes.
• /cache-tax guard warn: show the price and send. /cache-tax guard refuse brings back the default, drop once.

The author’s capture predates the cube row. Its two-cent ping is a receipt for one 75k-token Sonnet 5 session, not a fixed price.

How it works

The guard

• Cold is a clock, not a server check: a message is cold when 60 minutes have passed since the main agent’s last request, with no compaction in between. /clear resets it.
• It acts at 50,000 tokens of context or more, and prices the re-write from a table of list prices inside the module, matched to the session’s model.
• It drops a cold message once. Send it again to pay, or /clear and start from a note.
• Prompts nobody typed pass with the price logged: background task notifications, scheduled prompts, other sessions’ messages. Remote Control, Slack and channel messages keep the guard.
• Resumed sessions are checked from the resume fields Claude Code computes, so the first message back is covered.
• A paid cold write arms keepwarm for three hours, six with always on.

Keepwarm pings

After 50 idle minutes inside a window, the mod forks the session once, with no tools and the fixed prompt “Reply with the single word: warm”. The answer comes from cache and restarts the hour. If a ping read nothing, or wrote at least a tenth of what it read, the cache was already gone and the loop stops. A busy API (429, 529 or 5xx) is retried after 1, 2 and 4 minutes.

Windows belong to one session. A cold session, or a window restored after Claude Code restarts, waits for your next turn before it pings. With always on, each turn leaves at least six hours of window, so a session you abandon stops after at most seven pings.

The row’s cube is green when warm, orange when cold and grey before the first turn, beside the window, next ping and last readback. Ghostty and kitty draw it as an image; other terminals show [>]. The state is also written as a word, and NO_COLOR is respected.

What it reads, sends and stores

• Reads: whether your prompt starts with a slash, and nothing else of it. Also token counts, the model id, the context size, the command list, the theme and NO_COLOR. No files.
• Sends: only the keepwarm forks, over the session’s own transcript.
• Stores: each session’s keepwarm deadline and ping period, the always switch and the guard mode, in Claude Code’s plugin store. A session that never comes back leaves two small keys. The cold-write tally stays in memory.

Do the pings save money?

A ping costs a cache read plus the reply. A cold return costs a write of the whole context. On Fable 5.1 the write rate is 80 times the read rate ($20 against $0.25 per million tokens); on Opus 5.5 and Sonnet 5.5 it is 40 times. So up to 80 or 40 pings cost one cold write, and the card prints that figure for your model. A six-hour window is seven pings.

The real break-even is lower. A fork has no output cap, so a model that thinks before answering costs more than the read. Pings are also wasted if you come back after the window ends, or if switching model or effort breaks the cached prefix anyway.

On a subscription the dollars are a yardstick, not a bill. How cache reads count against the five-hour and weekly limits is undocumented, so the author suggests watching the rate-limit row of your status line during the first window.

What people say

• A cost to weigh. A MindStudio write-up from October 2026 sees cache-tax as trading one cost for another: better for long, steady sessions than for sparse use. It advises checking your real usage before and after, not a tool’s own figures.
• An all-day session, measured. In issue #24, a subscriber on Opus 5.5 in Claude Code Desktop came back from a three-and-a-half-hour break to a warm cache: 278k tokens read, 3.5k written. Later the fixed six-hour always window ran out, and the evening’s first message wrote 428k tokens. That report became the rolling always of version 2.3.0.

What’s new since September

This page first covered version 2.1.3. Since then:

• 2.2.0 and 2.2.1: the cube row above the prompt, following Claude’s light or dark theme.
• 2.2.2: price rows for Opus 5.5, Sonnet 5.5, Haiku 5.5 and Mythos, correct Opus 4 and 4.1 prices, prompts nobody typed pass, restored windows survive a restart, busy-API retries. Most came from user reports.
• 2.3.0: always rolls from your last turn instead of giving each session one six-hour window.
• 2.3.1: works on Team and Enterprise accounts, where Claude Code’s built-in security plugin hid the session-start event from the mod (issue #31).

Limitations

• The clock and the 50-minute ping assume the one-hour cache. On a five-minute cache the guard is late and the pings do nothing.
• Warm and cold are estimates from that clock. A warm ping proves the cache was warm at that moment, no more.
• On a resumed session the refusal’s token count is an upper bound. One refusal said 330,316 tokens and $6.61; the write that followed was 314k tokens, $6.28.
• The author has one transcript-verified return at the default interval (Fable 5.1, subscription, 19 September): the message at minute 62 read 156,886 tokens from cache and wrote 2,255. One run, not proof of savings in every setup.
• On Team and Enterprise accounts, an old resumed session’s first message is logged with its price instead of dropped.
• The cold-write tally is per session; /clear empties it.