cache-tax

cache-tax puts a price on coming back to a Claude Code session after an hour away. The prompt cache Claude Code uses expires after 60 minutes of silence, and the next message re-writes the whole context at the cache-write rate. When that is about to happen, cache-tax drops the message once and prints the bill; pressing Enter again sends it. It also keeps the cache warm for a window you set, and totals what the session’s cold writes cost. It is for people who pay per token through an API key, or who want to know what a long context costs to leave idle.

The author also ships cache-tax as a classic settings hook, in the karanb192/claude-code-hooks repository. The mod is the same idea rebuilt on function hooks, which gives it a timer, token counts and the ability to call the model, none of which a settings hook has.

What it does

• Guard. A message typed into a session whose cache lapsed over an hour ago, with more than 50,000 tokens of context, is dropped with the price of re-writing it and what a warm turn would have cost. The resend goes through unconditionally. /cache-tax guard warn shows the price and sends instead.
• Keepwarm. /keepwarm arms a six-hour window. /keepwarm 90m sets your own, /keepwarm always arms six hours at every session start, /keepwarm off stops and forgets both, /keepwarm status prints the status line. Inside the window, after 50 idle minutes, the mod sends one fork of the session with no tools and a fixed one-line prompt, which the server answers from cache and so refreshes the hour. A session that is already cold waits for your next turn before it pings. /keepwarm 6h every 2m sets a shorter ping period for testing, floor one minute, forgotten after the window.
• Auto-arm. After you pay a cold write, guarded or not, keepwarm arms itself for three hours.
• Score. /cache-tax prints a card: model, warm or cold, context size, cold price, keepwarm state, guard mode, break-even, and the session’s cold writes with their total.

Install

Needs Claude Code 2.1.287 or later, a one-hour prompt cache and Claude Code left running during the break. The author does not state a minimum version; the README’s validator output is from 2.1.276.

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

Since 18 September 2026 the mod has a repository of its own, karanb192/cache-tax, at version 2.1.3. The install commands have not changed: the marketplace is still karanb192/claude-code-mods, which also lists the same author’s fable-pin mod and mod-builder, a skill for building mods, and now points the cache-tax entry at the new repository. Restart Claude Code or run /reload-plugins. The guard is on by default; /keepwarm starts the warm window. If you already run the hook form of cache-tax, the mod detects its /cache-tax:status command at session start and tells you to keep one, because both together stop the same send twice.

Check the cache lifetime before you rely on the pings. Included subscription usage has a one-hour cache by default. API-key, usage-credit and cloud-provider sessions default to five minutes, and a ping every 50 minutes cannot protect that: set promptCacheTtl to "1h" in Claude Code’s settings for those billing paths.

How it works

The price comes from a table inside the module, not from your account: list prices for September 2026 per million tokens, matched against the session’s model id. Fable 5.1 is priced at $0.25 for a cache read, $20 for a one-hour cache write and $50 for output; Sonnet 5 at $0.20, $4 and $10; there are rows for Opus 5, Opus 4, older Sonnet and Haiku. A model id that matches no row shows n/a. Context size is the engine’s live window figure from $.session.usage(), with the turn’s summed usage as a fallback.

Cold is a clock. Every request of the main agent stamps its time on turn.step, and a message is cold when 60 minutes have passed since the last stamp and no compaction has happened in between. Compaction resets the context figure and the timer. /clear forgets everything priced before it. On a resumed session the mod seeds the clock from the resume fields Claude Code passes to settings hooks, so the guard can fire on the first message back.

The guard lives on prompt.submit. It reads the first non-blank character of your text to let slash commands through, and nothing else; the text is passed on untouched and never stored. A dropped message is remembered by the timestamp it was dropped at, so the same cold state passes on the second try.

A keepwarm ping is $.model.fork with the prompt “Reply with the single word: warm” and no tools. It is a real API request, the only thing that leaves the machine. It bills the cache read, its own few uncached tokens and whatever the model answers. The author’s figure is about five cents on a 200,000-token context when the answer is one word, against $4.00 for the re-write, but a fork takes no output cap, so a model that thinks before answering costs more. The card prints the read-only break-even, 80 pings on Fable 5.1, and the true number sits below it. The loop stops itself when a ping reads nothing or writes at least a tenth of what it read, since that means the cache was already gone.

It persists, in Claude Code’s plugin store, the keepwarm deadline and ping period keyed by session id, plus a global guard mode and the always switch. The cold-write tally is in memory and dies with the session. Nothing reads a file.

Limitations

• The 60-minute clock and the 50-minute ping assume the one-hour cache tier. On a five-minute cache the guard is late and the pings are useless.
• The author has one transcript-verified return at the default interval, Fable 5.1 on a subscription, 19 September 2026: a ping at minute 50 read 157k tokens and the message at minute 62 read 156,886 from cache and wrote 2,255. One run in one configuration; it shows the ping kept that cache alive past the hour, not net savings for every setup.
• The refusal’s token count is an upper bound. On a resumed session the engine’s context figure includes the last response’s output, which the mod cannot subtract; one refusal said 330,316 tokens and $6.61 and the write that followed was 314k tokens, $6.28.
• A warm ping proves the cache was warm at that moment. Switching model or effort, editing CLAUDE.md or changing the tool list breaks the cached prefix regardless of time, and the next real message pays.
• On a subscription the dollars are a yardstick, not a bill. How a cache read counts against the five-hour and weekly limits is not documented, and the author suggests watching the rate-limit row during the first window.
• The guard on a resumed session depends on Claude Code passing the resume fields; on older versions the first turn seeds it instead.
• A mod cannot draw into the status line, so the hook form’s status-line row does not carry over.