cache-clock

What it does

Every request to the model writes the conversation to the prompt cache. If your next request arrives before the cache expires, everything so far is read back at a fraction of the price. If it arrives after, the whole context is sent again at full price. Claude Code never shows you which side of that line you are on. cache-clock does.

It puts one line above the prompt with three things on it:

• How long until the prompt cache goes cold.
• How full the context window is.
• A separate sub clock for subagents while one is warm.

The countdown restarts on every model request. It turns yellow in the last quarter, red near the end, and pops a toast when the warning time is reached, optionally with a sound. At zero it says cache cold, and a toast tells you the next message is a full-price write.

Acting before the cache goes cold

At the warning, if Claude is idle and you haven't replied, the mod acts while the cache is still warm. You choose what it does with the onWarning setting:

• handoff (the default): Claude writes a handoff note, HANDOFF-<first 8 characters of the session id>.md, in the project root, in case you don't come back. Each session gets its own file, so parallel sessions in one folder don't overwrite each other.
• compact: the session compacts, as /compact does. The summary request reads the warm cache, so it is cheap, and your next message after the cache goes cold re-sends a few thousand tokens instead of the whole context.
• off: just the toast.

It runs once per idle stretch and re-arms when you send a message. The handoff is the only thing it ever sends to Claude: one short turn on a warm cache. Compact sends no turn at all.

You can also type /cache-clock to print the same line as text.

Settings

onWarning is a plugin setting. The rest are optional environment variables, and minutes may be fractional.

• CACHE_CLOCK_MAIN_TTL_MIN (60): pins the main session TTL. Leave it unset and the mod reads it from the transcript.
• CACHE_CLOCK_SUB_TTL_MIN (5): the subagent TTL.
• CACHE_CLOCK_WARN_MIN (5): when the toast, the warning action and the red colour kick in.
• CACHE_CLOCK_SOUND (off): 1 plays a sound with the warning toast.

To watch the whole cycle in two minutes, start Claude with CACHE_CLOCK_MAIN_TTL_MIN=2 CACHE_CLOCK_WARN_MIN=1.5.

How it works

Every model request restarts the main clock, or the sub clock for a subagent request.

The TTL is read from the session itself. After each turn the mod reads the end of the transcript for the newest main-thread usage.cache_creation: tokens in ephemeral_1h mean 1 hour, ephemeral_5m mean 5 minutes. Once it has seen one, the band says measured. On --resume it seeds the clock from the session's seconds_since_last_response.

Limits

• The clock counts from when each request was sent, so it can run a few seconds conservative.
• A message sent while the band says cold still works. It is just a full-price cache write.
• If none of the last 300 transcript lines wrote to the cache, the TTL keeps its previous or default value and is labelled assumed.
• State lives in memory, so after a hot reload the clock waits for the next turn.
• A later handoff in the same session overwrites that session's note, and it fires even if you have a draft typed but not sent. The draft stays in the box.
• In a narrow terminal the line drops pieces from the right (the TTL label, then sub, then ctx) instead of wrapping.