Keep-Warm

When a session pauses longer than its prompt-cache TTL and then resumes, the whole prefix is re-written at the cache-write rate, roughly 1.25 to 2 times the prefix cost on re-entry. A Keep-Warm ping reads the entry instead of writing it, refreshing the TTL at roughly a tenth of the prefix cost. That is the modeled economics, not the normal production behavior below.

Current shipped behavior: measurement, not automatic pinging

The watcher, forecasts, pause records, ledger, and reports are implemented, but the token-spending LLM ping ships disabled. keepwarm-enable records consent and can install the macOS scheduler; it does not remove that production ping gate. A normal tick returns llm-ping-disabled instead of issuing a model request. The internal dogfood escape hatch is not a supported user setup step. Read the ping economics below as the modeled/experimental path, not a promise of automatic cache refresh.

The Keep-Warm scheduler is implemented for macOS only. Linux and Windows report an unsupported scheduling gap; the Windows dashboard scheduled task is a different feature. The manual desktop Keep warm button is separate and runs only when clicked.

What it does

Prompt caches expire on a timer. Anthropic’s API cache holds a prefix for about an hour (five minutes on the shorter window). Step away past the timer and the next turn re-writes the entire cached prefix from scratch.

Keep-Warm watches paused sessions and evaluates whether a cache refresh could pay. Its modeled ping path would refresh the prefix before expiry, but normal production ticks stop at the disabled-LLM-ping gate; watching alone does not keep a cache warm.

This is the one feature designed to spend tokens on your behalf, so it is opt-in, gated by consent, and capped. Production builds keep the pings themselves switched off. Everything else in Token Optimizer is measurement or context shaping. Keep-Warm is the exception that touches your bill, and it is built to be honest about it.

Spends tokens, opt-in only

The experimental ping path spends tokens, requires consent, and normally refuses subscription billing. In the shipped production path, even enabling consent does not turn on LLM pings. Manual desktop refresh is separate and also uses the host.

API billing only

Keep-Warm runs only on API-billed sessions, where a cache read is genuinely cheaper than a prefix re-write in dollars. It refuses on subscription billing, because a subscription is flat-rate: a ping there spends rate-limit quota without saving money.

keepwarm-enable checks billing mode and will not arm pinging on a subscription. Subscription users get the quota-value story instead, which measures the right currency for that plan.

Billing detection recognizes ANTHROPIC_API_KEY or ANTHROPIC_AUTH_TOKEN and stored host auth state. That billing classification is not proof that production LLM pinging is enabled.

Commands

Keep-Warm has control, watcher, consent, and reporting verbs. They split into control, the automatic loop, consent, and reporting.

Control

cd ~/.claude/skills/token-optimizer/scripts
python3 measure.py keepwarm-enable     # consent + install scheduler (macOS); refuses on subscription
python3 measure.py keepwarm-disable    # terminal opt-out

keepwarm-enable records consent and installs the scheduler on macOS. keepwarm-disable is a terminal opt-out: a declined user is never asked again and never pinged.

The automatic loop

Three pieces record pauses and evaluate modeled ping decisions. The production ping gate still applies.

cd ~/.claude/skills/token-optimizer/scripts
python3 measure.py keepwarm-arm --quiet          # Stop hook: record that a session paused (token-free)
python3 measure.py keepwarm-tick --dry-run       # the brain: decide whether to ping, print decisions
python3 measure.py keepwarm-scheduler status     # install | uninstall | status

keepwarm-arm fires on the Stop hook for every plugin user and just records that a session paused. It is token-free and does not ping; actual pinging stays gated by consent. keepwarm-tick is the brain, run by the scheduler every five minutes: it evaluates armed sessions (time since pause, projected expiry, tripwire), but the production LLM-ping gate prevents a model request. keepwarm-scheduler manages the macOS launchd agent that runs the tick.

Use keepwarm-tick --dry-run to see exactly which sessions would be pinged and why, without firing anything.

Consent

cd ~/.claude/skills/token-optimizer/scripts
python3 measure.py keepwarm-consent-status    # machine-readable: billing_mode, consent, should_ask
python3 measure.py keepwarm-consent-asked     # mark the pitch as shown (idempotent)

keepwarm-consent-status returns JSON that skills read to decide whether to offer Keep-Warm at all. keepwarm-consent-asked records that the pitch was shown, and only ever moves the state from unasked to asked.

Reporting

cd ~/.claude/skills/token-optimizer/scripts
python3 measure.py keepwarm-forecast --days 30   # projected savings from YOUR history (before enabling)
python3 measure.py keepwarm-backfill --days 30   # replay the policy over real history
python3 measure.py keepwarm-report               # full money report (empty while pings are disabled)
python3 measure.py keepwarm-quota-value          # subscription users: value in quota, not dollars

keepwarm-forecast projects savings from your own session history before you enable anything, conservatively and read-only. keepwarm-backfill replays the policy over your real history in three modes (probe-only, predictor-sustain, oracle-sustain) to set the sustain promotion fence; it reads transcripts and writes only its promotion sidecar. keepwarm-report is the running money report. keepwarm-quota-value is the subscription counterpart, covered next.

The subscription quota-value story

On a subscription, dollars are the wrong yardstick. The plan is flat-rate, so a ping does not save money. The scarce resource is rate-limit quota, and a cold resume spends it: re-writing a lapsed prefix burns 1.25 to 2 times the prefix in quota that a warm read would have spared.

keepwarm-quota-value measures Keep-Warm in that currency. It models the realized-versus-spend ratio from a prior and folds in measured meter samples, so the value it reports is the quota a warm prefix saves rather than a dollar figure that would read as zero.

cd ~/.claude/skills/token-optimizer/scripts
python3 measure.py keepwarm-quota-value --json

Normal production pinging stays disabled. Subscription billing is also refused by the normal consent path; the CLI-only --limits-lab experiment is not the product default and does not bypass the LLM-ping gate. The quota-value report is the measurement instrument; it does not change the gate.

Honesty mechanisms

The experimental path records spend and has guards; modeled savings are not a guarantee of net benefit.

• Consent before firing. Pinging requires explicit keepwarm-enable. The arm hook records pauses but never pings without consent.
• Spend ledger and NET reporting. keepwarm-report shows pings, spend, realized savings, and the NET (savings minus ping cost) over 7 and 30 days, so the headline is what you actually netted, not gross savings.
• A tripwire. If realized savings stop justifying the spend, the tripwire trips and pinging backs off. Tick counts only successful pings toward its accounting, so a transient failure does not poison the math.
• Forecast before you commit. keepwarm-forecast and keepwarm-backfill let you see projected value from your own history before enabling.
• Subscription refusal. Pinging refuses on subscription billing, where it would spend quota for no dollar return.

Default state

Off. Even after keepwarm-enable, normal production ticks do not ping because the LLM-ping gate remains disabled. The keepwarm-arm hook fires on Stop for plugin users to record pauses, but recording is token-free and does not ping. Reporting commands are available without enabling pinging. backfill reads history and can write its promotion sidecar; it is not strictly read-only.

Platform availability: the pinging loop and scheduler target Claude Code on macOS (launchd); Linux/Windows scheduler installation is not implemented. See the capability matrix.

How to turn it on and off

To enable watcher consent and scheduling (API billing, macOS shown; not production pinging):

cd ~/.claude/skills/token-optimizer/scripts
python3 measure.py keepwarm-enable

To turn it off completely:

cd ~/.claude/skills/token-optimizer/scripts
python3 measure.py keepwarm-disable
python3 measure.py keepwarm-scheduler uninstall

keepwarm-disable is a terminal opt-out. Uninstalling the scheduler stops the tick loop so nothing evaluates armed sessions.

Defaults and thresholds

Setting	Default	Notes
Feature state	off	Opt-in via keepwarm-enable
Billing requirement	API only	Refuses on subscription
Tick interval	~5 minutes	macOS launchd only
Arm hook cost	token-free	Records pause, never pings
Ping cost	~0.1x prefix	Versus 1.25-2x for a cold re-write
Cache TTL refreshed	~1 hour (5 min short window)	Anthropic API cache
Tripwire	counts successful pings only	Backs off when NET stops justifying spend

The manual Keep warm button

The Claude desktop status bar (part of the Token Optimizer plugin) has a Keep warm button. It is not the daemon described on this page.

	Keep-Warm daemon	Keep warm button
Runs	watcher on a timer; production LLM pings disabled	only when you click
Billing	API billing only	any plan
Offered	while armed	only while the cache is still warm and its lifetime has been measured
After expiry	watcher evaluates sessions; no production ping	disappears when the cache expires
Cost	no production LLM ping; experimental spend tracked in keepwarm-report	a small amount of your usage per click; it tells you how many tokens it re-read from the cache

The daemon stays API-billing only and its consent rules are unchanged. The button never fires on its own. See the desktop status bar.

Risk rating

Production ticks do not issue LLM pings. Experimental pings and manual desktop refresh can spend tokens; consent, reporting, and tripwires limit the automatic experimental path but do not guarantee savings. The failure mode of a ping is a small wasted spend, capped by the tripwire and visible in keepwarm-report. If the tick or scheduler fails, no ping fires and you fall back to ordinary cold resumes.

Related environment variables

• ANTHROPIC_API_KEY / ANTHROPIC_AUTH_TOKEN (host billing/auth hints; not a production ping-enable switch)

Defined with defaults in the configuration reference.

Platform availability

Claude Code on macOS for the implemented scheduler; production token-spending pings remain disabled. Reporting commands run anywhere Token Optimizer does. See the capability matrix.

Related

• Cache TTL watchdog: cache-report measures the expiry waste Keep-Warm targets, before you decide to ping.
• Subagent prompt cache: the 1-hour TTL for subagent prefixes, advise-only by default, with explicit enable and automation opt-ins; under the explicit opt-in it still self-reverts if it does not pay.
• Cache economics: why a cold resume costs 1.25-2x the prefix.
• Your data and privacy: consent state and how to reset it.
• Configuration: Keep-Warm variables and consent keys.