claude-rewarm-guard

Claude Code caches your conversation prefix so each turn re-reads it at 10% of the input price instead of re-sending it at full price. That cache has a 1-hour TTL on the main thread. Walk away for lunch, come back, and type one more message: the entire prefix — every file you read, every tool result — is silently rebuilt at cache-write rates, 2× input.

A 400k-token Opus session costs about $3.80 to re-warm. Nothing tells you this happened. The turn just looks normal.

This package warns you first.

⚠️  Cache re-warm guard: this session holds ~412k cached tokens (claude-opus-4-8) and has
been idle 3.2h — past the 1-hour cache TTL, so this prompt rebuilds the whole prefix at
write rates ≈ $3.91. Re-send with WARMOK to proceed, or /clear (or a fresh session) to
avoid the rebuild.

Then you decide: pay it deliberately, or start fresh for free.

Install

npx claude-rewarm-guard install

It copies three hooks into ~/.claude/hooks/rewarm-guard/ and wires them into ~/.claude/settings.json. Nothing else in your settings is touched, and the runtime is self-contained — it keeps working after the npx cache is cleared.

npx claude-rewarm-guard uninstall     # removes both, cleanly

What did this already cost me?

Before you install anything, ask what idle-resume re-warms have already cost you. The answer is sitting in your local transcripts.

npx claude-rewarm-guard report

Idle-resume cache re-warms — all local history, 212 sessions

  Re-warm events        96
  Tokens rebuilt        38.4M
  Avoidable cost        $412.60
  Share of cache writes 34%  (of $1204.18 total)

  By model
    claude-opus-4-8                71 events    29.1M    $276.45
    claude-sonnet-5                25 events     9.3M    $136.15

  At your current threshold (costFloor $1.00, idle 50m), the gate would have
  warned on 88 of these 96 events — $398.90 of $412.60 (97%).

The last line is the point: it prices your thresholds against your history, so you can tune the gate on evidence instead of taste.

That share is the number worth internalizing. On the history that motivated this tool, a third of everything spent on cache writes was rebuilding prefixes that had already been cached — not new context, just the same context, paid for twice.

Method. Within a single session, an assistant turn that follows a >1h gap and writes

50k tokens of cache is rebuilding a prefix that had already been cached and expired. Those tokens would otherwise have been reads, so the avoidable cost is the write/read spread — 1.9× input, per token. Requests are deduped by id, so retries count once.

How it works

Three hooks, all fail-open:

| Hook | Event | Job | | --- | --- | --- | | capture.mjs | SessionStart | Record the resolved model — SessionStart is the only hook handed one | | gate.mjs | UserPromptSubmit | Price the rebuild; block only if it's expensive | | cleanup.mjs | SessionEnd | Drop the state file |

The gate blocks only when all three hold: the prompt lacks the approval keyword, the session has been idle past idleMinutes, and the estimated rebuild exceeds costFloor. Any missing field, unreadable file, or parse error allows the prompt through. A cost warning must never wedge you out of your own session.

Why the model needs capturing. Pricing a rebuild means knowing which model you're on, and only SessionStart receives that — with --model overrides already resolved. But a mid-session /model switch leaves that capture stale while the transcript's last turn holds the truth. The gate takes whichever was observed more recently.

Why it's main-thread-only. Only the main thread submits user prompts. Subagents run on a 5-minute cache TTL and are never resumed, so there is nothing to gate.

Configuration

install flags write ~/.claude/rewarm-guard.json, which you can also just edit.

npx claude-rewarm-guard install --cost-floor 5 --idle-min 55 --keyword REBUILD

| Key | Default | | | --- | --- | --- | | idleMinutes | 50 | Minutes idle before the 1h cache is treated as cold. Under 60 so you're warned before the cliff, not after | | costFloor | 1.0 | Only warn above this many dollars | | keyword | WARMOK | Put this anywhere in a prompt to approve the rebuild | | premium | 1.9 | The write/read spread: 2.0× input to write, 0.1× to read | | rates | opus 5, sonnet 3, haiku 1, fable 10 | Input $/1M by model family | | defaultRate | 5 | For families released after this version |

Run npx claude-rewarm-guard status to see what's wired and how it's tuned.

Notes

• Managed settings. If your settings.json is generated (chezmoi, Nix, dotfile templating), don't let the installer rewrite it: install --print emits just the hook JSON for you to paste into your source of truth. Point --settings <path> at a different file to target a project- or enterprise-scoped one.
• Restart any running session to pick the hooks up.
• Prices are list rates and change; the gate is an order-of-magnitude warning, not a bill.
• Requires Node 18+. No other dependencies.

License

MIT