cache-caffeine: Claude Code mod: keeps the prompt cache warm while you step away, and…

# 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 ` | 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 ` | 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