cache-tax — Claude Code plugin: what it does, how to install
cache-tax prices a cold return to a session before you send the next message, so a lapsed 1-hour prompt cache does not quietly re-write the whole context.
MIT ★ 586 updated 2026-10-26
/plugin marketplace add karanb192/claude-code-hooks
/plugin install cache-tax@claude-code-hooksWhat cache-tax does
The plugin keeps an eye on Claude's 1-hour prompt cache and puts a number on coming back late. Every UserPromptSubmit it pulls the newest usage block out of the session transcript. If the cache lapsed and the context is bigger than CACHE_TAX_BIG (50000 tokens by default), the re-write cost shows up as a warning before your message goes out. With CACHE_TAX_BLOCK=1 it refuses once instead, exit code 2, and resending the same text gets through.
A SessionStart hook handles resume and fork: idle gap, tokens the first message re-writes, dollar estimate. /cache-tax:status renders the full card on demand, with this session's cache writes, reads and full re-writes so far.
No plugin can ship a status line, so that part you wire yourself: node ~/.claude/cache-tax.js --statusline prints one line to drop into your own script. Without node on the machine it will not run, and below v2.1.251 the script falls back to reading the transcript rather than the native prompt_cache object. Slash commands never reach the guard, so /clear and /compact stay quiet.
What it helps with
- see what returning to an idle session costs before sending
- skip a full context re-write after an hour away
- stop an accidental cold send with a one-time refusal
- check how much cache the session has written and re-read
- add remaining cache minutes to an existing status line
Example prompts for the agent
- Run
/cache-tax:statusand tell me what a cold return would cost right now. - Set
CACHE_TAX_BLOCK=1so the guard refuses a cold prompt once. - Run
node ~/.claude/cache-tax.js --statuslineand add that line to my status line script.
How to install cache-tax
Plugin marketplace
/plugin marketplace add karanb192/claude-code-hooks/plugin install cache-tax@claude-code-hooksStep by step, with commands for each platform: Claude Code plugins: marketplaces, installing, and building your own
Questions about cache-tax
How to install cache-tax in Claude Code?
Run /plugin marketplace add karanb192/claude-code-hooks, then /plugin install cache-tax@claude-code-hooks. Restart Claude afterwards.
What does cache-tax do?
It puts a dollar figure on a cold return to a session. You get a warning before a cold prompt, a price for a stale resume, and a full card from /cache-tax:status.
How is it different from the resume dialog Claude already shows?
The native dialog covers resuming an old session and speaks in tokens. This plugin adds the dollar estimate, and it also catches a session you left open and typed into, where nothing native steps in.
Source text
cache-tax · MIT
# cache-tax

> The comeback price of a cold prompt cache, shown before you pay it.
Claude Code's main conversation rides a 1-hour prompt cache. Come back at minute 59 and the next message costs cents. Come back at minute 61 and the whole context is re-written at the cache-write rate, which on Fable 5.1 is 80x a cache read ($20 against $0.25 per million tokens). A 500k-token session re-cached cold is $10 at list price, and the message that triggers it is usually "good morning". Claude Code computes all of this and shows none of it at the moment you press Enter. This plugin does.
## A cache countdown row in a status line you already have
No plugin install needed. `cache-tax.js` is one file with no dependencies. Copy it, then call it from your own status line script with the same stdin Claude Code sends you, and print its line as one more row:
```
curl -fsSL https://raw.githubusercontent.com/karanb192/claude-code-hooks/main/plugins/cache-tax/cache-tax.js -o ~/.claude/cache-tax.js
```
```sh
# inside your status line script, where $input holds the JSON Claude Code piped in
printf '%s' "$input" | node ~/.claude/cache-tax.js --statusline
```
It prints one line, while warm and then after the cache lapses:
```
cache 47m left · 218k · cold costs $4.37 · last miss ttl_expired_1h
cache COLD · next msg re-writes 218k = $4.37 · last miss ttl_expired_1h
```
It reads the native `prompt_cache` object Claude Code sends to status lines (v2.1.251+), so Claude Code re-runs it the moment the cache goes cold; on older versions it falls back to the transcript named in the same payload. The guard and the resume price below are the plugin; the row works without it.
## Install
```
/plugin marketplace add karanb192/claude-code-hooks # once per machine
/plugin install cache-tax@claude-code-hooks
```
Restart Claude Code, done. (Or from a shell: `claude plugin install cache-tax@claude-code-hooks`.)
## What it does
| Event | Runs | What happens |
|-------|------|--------------|
| UserPromptSubmit | sync, ~30 ms | Reads the newest usage block from the session transcript. If the cache has lapsed and the context is over `CACHE_TAX_BIG` tokens, shows the re-write cost as a warning. With `CACHE_TAX_BLOCK=1` it refuses the prompt once instead (exit 2); resend the same message to proceed, or `/clear` and start from a handoff note. |
| SessionStart (`resume\|fork`) | sync | On a cold resume, prints the idle gap, the tokens the first message re-writes, and the dollar estimate Claude Code already computed (`estimated_cache_write_usd`, v2.1.251+). Falls back to the transcript on older versions. |
`/cache-tax:status` renders the full card on demand: tier, warm or cold, context size, cold-comeback price, and this session's cache writes, reads and full re-writes so far. From a shell, `node cache-tax.js --render --transcript <path>` renders the same card for any transcript; without `--transcript` it picks the newest transcript for the current directory.
The guard ignores slash commands, so `/clear` and `/compact` never trigger it. After a compaction (manual or auto) the old context no longer applies, so until the first new turn lands the status line reads `cache reset by /compact · 17k carried · next msg writes ≥ $0.34`, the card says the same, and the guard stays quiet: the summary has never been cached, so that first write is unavoidable and small.
### The warning, verbatim
```
cache-tax: the 1h prompt cache lapsed 2h00m ago. This message re-writes 300,002 tokens at $20/MTok = $6.00
(a warm turn would have cost $0.08). If most of that context is stale, /clear and start from a handoff note instead.
```
## The Mod form
The same tool exists as a Claude Mod, [cache-tax@claude-code-mods](https://github.com/karanb192/claude-code-mods/tree/main/plugins/cache-tax), for [Claude Code 2.1.287 or later](https://code.claude.com/docs/en/plugins/mods/overview#turn-mods-on-or-off), where mods are on by default. It runs inside Claude Code instead of reading the transcript, refuses a cold send once by default, and adds what a hook cannot do: `/keepwarm 6h` sends one cache-shared ping after 50 idle minutes so the cache is read, not re-written, when you come back. Install one form, not both; two guards fire twice. The status line segment below stays with this hook's files either way, because a mod cannot draw into the status line.
## What Claude Code already does, and where this adds
On `--resume` of a session older than its cache TTL, recent Claude Code versions (seen on 2.1.261) show their own dialog, "this session is N old and M tokens, we recommend resuming from a summary". That covers the resume path in tokens. cache-tax adds the dollar figure there, and covers the case that dialog cannot see: a session you left open, came back to after an hour, and typed into. Nothing native intervenes at that keystroke.
## Status line segment
Plugins cannot ship a status line, so wire this one yourself. The same script prints one line when called with `--statusline`, and it prefers the native `prompt_cache` object Claude Code sends to status lines since v2.1.251 (`expires_at`, `recache_tokens_if_cold`, `ttl`, `last_miss_cause`), which also means Claude Code re-runs it the moment the cache goes cold.
```json
"statusLine": {
"type": "command",
"command": "node ~/.claude/plugins/marketplaces/claude-code-hooks/plugins/cache-tax/cache-tax.js --statusline"
}
```
Output while warm, then after the cache lapses:
```
cache 47m left · 218k · cold costs $4.37 · last miss ttl_expired_1h
cache COLD · next msg re-writes 218k = $4.37 · last miss ttl_expired_1h
```
That path is the marketplace clone Claude Code keeps after `/plugin marketplace add`; the installed copy also lives under `~/.claude/plugins/cache/claude-code-hooks/cache-tax/<version>/`. Already have a status line script? Pipe the same stdin into `cache-tax.js --statusline` and print its line as one more row.
## Configuration
All optional, set via environment variables:
| Variable | Default | Purpose |
|----------|---------|---------|
| `CACHE_TAX_BIG` | `50000` | Context size in tokens below which the guard stays quiet. |
| `CACHE_TAX_BLOCK` | unset | `1` makes the guard refuse a cold prompt once (exit 2) instead of warning. The resend goes through. |
| `CACHE_TAX_TTL` | auto | Force `5m` or `1h` when the transcript has no cache-write tier to infer from. |
| `CACHE_TAX_PRICES` | list rates | JSON overriding per-family prices as `[cache read, 5m write, 1h write]` in $/MTok, e.g. `{"fable-5-1":[0.25,12.5,20]}`. |
Built-in list rates (October 2026): Fable 5.1 and Mythos 5.1 `[0.25, 12.5, 20]`, Fable 5 and Mythos 5 `[1, 12.5, 20]`, Opus 5.5 `[0.2, 5, 8]`, Opus 5 and 4.5 to 4.8 `[0.5, 6.25, 10]`, Opus 4 and 4.1 `[1.5, 18.75, 30]`, Sonnet 5.5 `[0.1, 2.5, 4]`, Sonnet 5 `[0.2, 2.5, 4]`, Sonnet 4.x `[0.3, 3.75, 6]`, Haiku 5.5 `[0.01, 0.125, 0.2]` up to 100k prompt tokens and `[0.05, 0.625, 1]` above, Haiku 4.5 `[0.1, 1.25, 2]`, Haiku 3.5 `[0.08, 1, 1.6]`. Unknown models get token counts and no dollar figure. If you are on a subscription the dollars are what the same traffic would cost at API list price, which is the only public yardstick; how a cache write weighs against your plan limits is not documented.
## How it decides
The tier comes from the newest assistant usage block in the transcript: `cache_creation.ephemeral_1h_input_tokens` means the 1h tier, `ephemeral_5m_input_tokens` the 5m tier. Age is wall-clock time since that block's timestamp. Lapsed means age past the tier's TTL; the "lapsed N ago" figure is the time since that expiry, not since the block. The re-write cost is the block's full context (input plus cache read plus cache write) at the tier's write rate. A "full miss" on the card is a request whose cache read covered under half of the previous request's context while its write covered over half of it.
Hooks receive no token counts, so nothing here comes from the hook input except the resume fields Claude Code added in v2.1.251. Everything else is read from `transcript_path`, the file Claude Code is already writing.
## Limits
- Claude Code only. It reads the transcript Claude Code writes and the fields Claude Code sends; nothing here runs under Codex, Cursor or a raw API client.
- Needs node on PATH, like every plugin in this marketplace.
- The status line row is wired by hand (plugins cannot ship one), so the countdown is only as live as your `refreshInterval`; the cold flip itself is event-driven and needs no timer.
- Dollars are API list prices. On a subscription they are the yardstick, not the bill, and how a cache write weighs against the 5-hour and weekly limits is not documented anywhere I could find.
- The guard reads the newest real turn in the transcript. A session whose last request was a subagent's is priced from that request, which can be smaller than the context you are about to send.
- After a compaction the figure is a floor. The transcript records the tokens carried into the summary (`compactMetadata.postTokens`) but not the system prompt and tools that go in front of them; on one 562k session the row said `≥ $0.34` and the first message wrote 40k tokens, $0.80.
- `/compact` is not a free exit from a cold cache. The compaction request sends the whole context to the model once more, and Claude Code does not write that request's usage to the transcript, so neither the guard nor the card's session totals see it. If the cache has lapsed and most of the context is stale, `/clear` plus a handoff note is the cheap way out.
- Two tests pin the false-positive side (warm session, small context) so the guard stays quiet where it should; there is no corpus beyond the test file.
## Related tools
[claude-hud](https://github.com/jarrodwatts/claude-hud) and [ccstatusline](https://github.com/Haleclipse/CCometixLine) show a cache countdown in the status line and price writes at a fixed 1.25x, the 5-minute tier. [cc-cache-alert](https://github.com/candiesdoodle/cc-cache-alert) pings your phone before the cache lapses so you can send a keepalive. [ccusage](https://github.com/ccusage/ccusage) prices the 1-hour tier correctly, after the fact, in reports. cache-tax is the one that puts a dollar figure on the keystroke and can refuse it.
## Data & privacy
Reads the session transcript's usage blocks and timestamps, never message text. Writes a one-line JSON entry to `~/.claude/hooks-logs/<date>.jsonl` when it warns or blocks, and a tiny acknowledgement file under `~/.claude/cache-tax/` in block mode. No network calls (the script only uses `fs`, `path`, and `os`).
## Uninstall
```
/plugin uninstall cache-tax@claude-code-hooks
```
© Karan Bansal · MIT · karanb192/claude-code-hooks