<p align="center"><img src=".claude-plugin/icon.png" width="128" alt="cache-caffeine"></p>

cache-caffeine

A Claude Code mod that keeps the prompt cache warm while you step away, and wakes Claude up when the usage limit resets.

Claude Code caches the conversation for 1 hour on a Claude subscription and 5 minutes on an API key. Come back after it expires and the next turn writes the whole context to the cache again. With caffeine on, a short poke goes out before the cache expires, so your next turn reads the cache instead.

 ≋≋≋
c[_] 98°F  caffeine on · poke at 14:32 (in 40m) · until you turn it off (or 8h idle)   t: turn off   e: message

The cup is the cache: 100°F and steaming right after a request, cooling to 40°F as the cache runs out, red through blue. It shows while caffeine is off too, so you can watch the cache go cold.

Near the usage limit a second row offers the wake:

5h limit 96% · resets 14:10 (in 2h 05m)   u: wake Claude at 14:12   n: not now

Install

/plugin marketplace add lperezmo/cache-caffeine
/plugin install cache-caffeine@cache-caffeine

Needs Claude Code 2.1.287 or newer (mods on by default).

Use

The row above the prompt has the switch (t) and the message editor (e), and says how long caffeine keeps warm: until you turn it off, or to the end of a warm or until you set; the wake row books the wake (u) or puts it off (n). Focus the row with ctrl+x tab or a click.

| Command | What it does | | --- | --- | | /caffeine | on (until you turn it off) or off, for this session | | /caffeine warm 2h | keep the cache warm for 2 hours, then off (alone: 1 hour) | | /caffeine until 18:00 | on, then off at 18:00 | | /caffeine poke | poke now | | /caffeine message <text> | what the poke says (reset for the default, "poke, just say okay") | | /caffeine every 10m | how long after the last request to poke (auto: at 80% of the cache's life, 48m on a 1h cache, 4m on 5m) | | /caffeine ttl 1h | pin the cache TTL (auto to go back to detecting it) | | /caffeine idle 8h | turn off after this long without a turn of your own | | /caffeine forever | no end this time: asks you to confirm, then keeps the cache warm until you turn it off; the next turn-on has the idle stop again (idle off does the same) | | /caffeine band off | no row; shows in the status line instead, for when other mods use the band | | /caffeine auto 100k | turn on by itself once the context passes 100k tokens (off for never, the default) | | /caffeine cost | what a poke costs against one cache rewrite, and how long caffeine pays off for | | /caffeine wake | wake Claude just after the usage limit resets | | /caffeine 1 min | wake Claude at a time: in 20 minutes, 2 hours, 14:30, at 3pm, noon (wake 1 min works too); wake off cancels | | /caffeine 20 min check the build | a wake that tells Claude exactly that | | /caffeine wake prompt <text> | what Claude is told on every wake (wake prompt default goes back to the defaults) | | /caffeine wake auto | book the wake by itself whenever the limit hits | | /caffeine status | what it is doing and whether the last poke found the cache warm |

What it does and does not do

• It sends prompts on your behalf. Each poke is a real turn: it uses your plan's usage and adds a short exchange to the conversation. A poke is exactly the message you set (default "poke, just say okay"), and a wake is exactly the text you gave that wake (/caffeine 20 min check the build), else the wake prompt you set, else the default ("The usage limit has reset. Pick up where you left off." after a limit reset, "Time's up. Pick up where you left off." at a time you picked), with [caffeine] in front. Nothing read from the conversation, a file or anywhere else goes into either.
• It is off until you turn it on, and only for the session you turn it on in. It waits while Claude is working and pauses when the 5-hour window is over 90% or the weekly one over 95%.
• It skips the poke once the cache has already expired, since that would only write it again. If a poke finds the cache cold anyway (it writes more than a tenth of what it reads), caffeine turns itself off and says so. A compaction or a /clear empties the cache, so pokes wait for your next message to write it again; a poke that had to write it anyway (the first after a compaction or a model switch) never counts as cold.
• It turns itself off after 8 hours without a turn of your own, unless you confirm /caffeine forever for that run (change the length with /caffeine idle).
• What it reads: the session's own usage figures from Claude Code (token counts per request, the running cost estimate, the 5-hour and weekly limit windows) and three environment variables, CLAUDE_CODE_PROMPT_CACHE_TTL, FORCE_PROMPT_CACHING_5M and ENABLE_PROMPT_CACHING_1H. From those it works out the cache TTL: what a request cost (a 1-hour write costs 2x input, a 5-minute one 1.25x), else the variables, else request timing (the cache still read after more than 5 minutes idle means 1 hour), else Claude Code's default for your plan. It reads no files and makes no network requests of its own.
• Tools it calls itself: none. A wake is caffeine's own timer: at the wake time it sends the wake prompt the same way it sends a poke. /caffeine forever asks you to confirm in Claude Code's own question dialog.
• Programs it starts: none. It does not keep the computer awake: a wake (and the pokes) need it on and the session open, so set your power settings to stay awake if you rely on them.
• Hooks that see other events: prompt.submit only clears the "limit hit" flag when you send a prompt; it changes nothing. classic.StopFailure only notices a reply that failed on the usage limit, to offer the wake. turn.step reads each request's usage and leaves the request as it is. session.compact and session.end only note that a compaction or a /clear happened, to hold the pokes.
• The session has to stay open. caffeine keeps a booked wake's time in its own storage, so after claude --resume it picks the wake back up.

License

MIT