cache-warmer: keep the prompt cache warm through breaks

Problem

Claude keeps a cached copy of your conversation so that each new message is cheap. That cache lasts only five minutes or an hour after your last message, depending on how you pay for Claude. When it runs out, your next message pays to rebuild it from scratch, and on a long conversation that costs a dollar or two every time.

A meeting or a coffee break easily outlasts the cache. You will most likely come back and send another message, so you pay that rebuild for having stepped away.

How Claude prompt caching works

Every message you send carries the whole conversation so far. Claude charges far less for the part it has seen recently: on Opus 5.5, reading it from the cache costs a twentieth of sending it fresh, while putting it into the cache costs more than sending it fresh. Each read also restarts the cache's timer, so the cache stays warm for as long as you keep talking.

Most other Claude models read at 0.1× input; Fable 5.1 and Mythos 5.1 read at 0.025×.

Solution

cache-warmer, a Claude Code mod, keeps the cache warm while you are away. Shortly before the cache would expire, it sends a small background request that reads the cache and restarts its timer for a few cents. When you come back, your next message finds the cache still warm. The background request never enters your conversation, and the transcript gets one coffee-cup notice row per refresh.

It refreshes only when that is likely to save money, so a short conversation that is cheap to rebuild is left alone. If you do not come back, it stops after a few refreshes, so an abandoned session stops costing anything.

How it works

Each refresh forks the main conversation with one short prompt. A fork inherits the parent's system prompt, tools, and history exactly, so its first request reads the parent's cache and resets its lifetime at the read price.

Following the rule from Pi, Mario Zechner's coding agent, it refreshes only when the expected saving is at least $0.05, where the expected saving is the chance of another prompt before expiry times the extra cost of a rewrite, minus the refresh cost. An idle session counts that chance as 15%, so idle refreshes start at about 104k tokens on the 5-minute cache and 56k on the 1-hour cache for Opus 5.5.

• /cache-warmer opens a menu you move through with the keyboard. Global configuration saves the default lifetime and the idle limits for new sessions. Session configuration changes this session's lifetime until its first response locks it; /clear unlocks it.
• An idle session stops warming after a set number of refreshes, 5 by default for each lifetime and adjustable from 0 to 20. Five refreshes keep an idle 5-minute cache for 27m30s and an idle 1-hour cache for 5h30m, which covers a lunch break. Pi stops idle warming at 30 minutes, so it never refreshes an idle 1-hour cache.
• Analytics shows refreshes, the warming fee, the fee spent on refreshes no prompt followed, and the net saving, for the session and for all time. A prompt counts as kept when it reads the cache after the point where, without refreshes, the cache would have expired; it is credited with the cached tokens it read times the write price minus the read price. Debug mode shows each refresh and writes a JSONL log.
• A Claude Code mod can only fork, so each refresh writes a short prompt and produces about 200 output tokens. At 300k tokens a refresh costs $0.064, against $0.060 for Pi's one-token re-send.

How Claude Code assigns lifetimes

Claude Code puts every request in one of two groups. The main conversation covers your turns and -p runs. Everything else covers subagents, forks, compaction, and session titles, and it stays at 5 minutes unless subagentPromptCacheTtl says otherwise. FORCE_PROMPT_CACHING_5M=1 overrides both groups, then the environment variables, then the settings.

These actions break the cache whatever its lifetime: switching models, changing effort on routes that key the cache on it, turning on fast mode for the first time, adding or removing tool definitions, compacting, and the first session after a Claude Code upgrade. /usage shows the session's hit ratio and the likely cause of the last miss.

Claude subscription, API key, and Amazon Bedrock

1. ¹ 5 minutes once usage credits are billed.
2. ² Claude 4.5 and later models, including Opus 5.5.
3. ³ How cache tokens count toward plan limits is not documented.
4. ⁴ On Opus 5.5, Sonnet 5.5, and Fable 5.1.

A gateway set with ANTHROPIC_BASE_URL caches only if it forwards Claude Code's cache_control markers unchanged, and the 1-hour lifetime also needs the anthropic-beta header passed through.

Benefits

On an average day, you save a couple of dollars several times over: each avoided rewrite at 300k tokens is worth $1.44 on the 5-minute cache and $2.34 on the 1-hour cache, after the read.

Live test

Four parallel Claude Code sessions with a 159k-token prompt, each idle after its last real prompt. The control has no mod.

The control expired, so the kept caches came from the refreshes, not from the provider holding entries past their lifetime. A fork in the default 5-minute group extends a 1-hour entry, so no extra setting is needed. Without warming, the 5-minute session would have rewritten about $0.76 of cache and each 1-hour session about $1.24.

Modeled four-hour day

35 requests with one 66-minute break and nine 14-minute breaks: the 1-hour cache expires once and the 5-minute cache ten times. Context grows to 300k tokens by request 8.

On this day, the 1-hour cache with cache-warmer is the cheapest setup. The 66-minute break still expires the 5-minute cache, because five idle refreshes cover 27m30s. The modeled day uses cache-warmer 0.6.1 with its default idle limits.

Caveats

• If you work interactively and attentively all day, with no gap longer than the cache lifetime, your own prompts keep the cache warm and the mod adds little.
• Below the break-even size, about 104k tokens on the 5-minute cache, the mod skips refreshes, so it neither costs nor saves anything.
• A session you abandon pays for five refreshes, about $0.32 at 300k tokens on either lifetime: over 27m30s on the 5-minute cache and over 5h30m on the 1-hour cache. Lower the idle limit to pay less.
• Model switches, compaction, and the other actions above still rebuild the cache; warming does not prevent them.
• These are API-equivalent costs. On a subscription, the saving is plan usage rather than dollars.

Final statements

Running several long sessions in parallel is becoming common. In that setup, you miss many caches throughout the day, and cache-warmer saves on each session. It might be only $10 a day, but over 250 working days that is $2,500.