Cache Tax plugin
A Claude Code mod that warms the prompt cache during breaks and shows the rewrite cost before a message goes into a cold session
- 384 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- Every warming request spends tokens of your subscription or API key, and the model output in it is uncapped
- The mod sees every prompt you type and the model's replies with token counts, though prompt text is not kept or logged
- Keeps the warming window deadline and the guard mode for sessions in Claude Code's local store
Install
- Works in
Manual install
claude plugin marketplace add karanb192/claude-code-modsNeeds Claude Code 2.1.287 or newer; mods are on by default.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- Every warming request spends tokens of your subscription or API key, and the model output in it is uncapped
- The mod sees every prompt you type and the model's replies with token counts, though prompt text is not kept or logged
- Keeps the warming window deadline and the guard mode for sessions in Claude Code's local store
This is third-party code. Review the repository files before installing.
What it does
Cache Tax tackles a cold prompt cache. When the cache expires, even a short request like "give me a recap" makes Claude Code rewrite the whole old context, and the bill grows. The mod does two things: it warms the cache during a break and stops a send into a cold session until you see the price. The `/keepwarm` command arms a six-hour warming window, `/keepwarm 90m` sets your own length and `/keepwarm off` stops it. After 50 idle minutes a timer inside Claude Code sends one tool-less request over the session transcript. The mod reads usage after every ping and stops if reads are zero or writes reach 10 percent of reads. When you come back, the cache has gone cold and the context is at least 50,000 tokens, the guard drops your message once and shows the estimated rewrite. Sending again goes through, and after a detected cold write warming arms for at least three hours. The `/cache-tax` command shows a card with the cache estimate, the warming window and the session's cold-write tally. While warming is on, a cube sits above the prompt: green for warm, orange for cold, grey before the first turn.
Who it is for. For people who often step away from a long Claude Code session and do not want to pay for a sudden rewrite of a large context on return.
Good fit when
- You step out for lunch or a meeting with hundreds of thousands of tokens of context in the session and want to return to a warm cache
- You want to know the price before sending: the mod shows the rewrite estimate and offers to start over with `/clear` and a note
- You work on a subscription with a one-hour cache and want the warming window to cover breaks up to six hours
- You want to see how many cold writes already happened in the session, with `/cache-tax`
- You prefer settings hooks: a separate hook version warns by default and refuses once with `CACHE_TAX_BLOCK=1`
Not a fit when
- You do not step away for long: warming spends tokens, and the window should match when you expect to return
- Your Claude Code is older than 2.1.287: mods are unavailable there
- The session runs on an API key, credits or a cloud provider with a five-minute cache and you have not set `promptCacheTtl` to `"1h"`: the 50-minute schedule assumes a one-hour cache
- Claude Code does not stay running during the break: the timer lives inside the process
Example request
I am stepping away for an hour and a half: arm cache warming for 90 minutes and show what coming back would cost if the cache goes coldLimitations
- Mods require Claude Code 2.1.287 or newer, and local settings, safe mode or organization policy can stop them from loading.
- The 50-minute schedule assumes a one-hour main cache. A subscription gives it by default, while API key, credit and cloud sessions need `promptCacheTtl` set to `"1h"`.
- The reply to a warming request also costs tokens, and output is uncapped.
- The amount in a refusal is an upper bound: the token count comes from the last response together with its output.
- The hook and the mod share a name and should not be kept together, or every cold message gets two guards.
- The cache can reset because of a prefix change regardless of time.
How to disable. `/keepwarm off` stops warming and forgets the window. `claude plugin uninstall cache-tax@claude-code-mods` removes the guard itself, and the switch for all mods is described under Mod controls in the Claude Code docs.
FAQ
How do I install Cache Tax in Claude Code?
Run `claude plugin marketplace add karanb192/claude-code-mods`, then `claude plugin install cache-tax@claude-code-mods`. Restart Claude Code or run /reload-plugins. Claude Code 2.1.287 or newer is required and no early-access flag is needed.
How much does keeping the cache warm with keepwarm cost?
Each warming request pays for a cache read, a few uncached tokens and the model's reply at the output rate. In a recorded run the status showed 75k tokens read at $0.02. The mod stops if nothing is read or writes reach a tenth of reads.
Why did a short request cost so much after a break?
When the cache has expired, even a recap request makes the old context get rewritten. In a recorded refusal a two-line recap in a 330k-token session got a $6.61 estimate, and after resending the actual write cost $6.28.
What does the guard do when I return to a cold session?
If the context is at least 50,000 tokens and the one-hour cache clock says cold, the guard drops your ordinary message once and shows the rewrite estimate. To continue, send the message again or run /clear and start from a note.
How is the mod different from the hook version?
The hook version warns by default, refuses once with `CACHE_TAX_BLOCK=1` and provides a standalone status-line countdown. Warming exists only in the mod. Keeping both is not advised: a cold message would get two guards.
Discussion
No questions or reviews yet.
Related
PluginsA Claude Code skill that keeps the prompt cache warm during idle time so your next message is read from cache.
A Claude Code plugin that picks the model's effort level for every prompt and shows the prompt cache countdown
A Claude Code plugin draws a band above the prompt with remaining 7-day and 5-hour limits and the prompt cache state
Four Claude Code mods: cache cost, screen-recording masking, a /goal meter and a guard against edit conflicts
A Claude Code status line with 5-hour and weekly limit usage, reset countdowns, model and prompt cache lifetime
claudetop shows session cost, cache hit rate, plan limit windows and overspend alerts in the Claude Code status line
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Repository stars | Main difference |
|---|---|---|---|
| Cache Tax (this card) | no | 384 | |
| ccusage | no | 19,415 | token and cost reports from local logs; it neither warms the cache nor stops a send |
| Claude Code Karma | no | 339 | a local dashboard of Claude Code sessions with token costs, with no warming and no cold-send guard |
README in short
The page shows a recorded refusal with a $6.61 estimate and walks through installation, how it works, the cost of warming and the commands. It then covers the status row with the cube, what the mod can reach in Claude Code, a threat model, limits and a way to prove warming on your own session.