DEV Community

Cover image for Prompt Cache Control puts a live countdown on Claude Code’s 5 minute cache
Daniel (San) Ávila
Daniel (San) Ávila

Posted on Originally published at Medium

Prompt Cache Control puts a live countdown on Claude Code’s 5 minute cache

#ai #claude #devtools #productivity

Claude Code already caches your prompt prefix. What it does not tell you is how much of the last request the cache actually served, or how many seconds you have left before that cache lapses and you pay to write the whole thing again.

That number matters most exactly when you are not looking at it. You read a long file, Claude answers, you go think for six minutes, you come back and type one line, and that one line costs you a full rewrite of a 150k token prefix.

What the band shows

One row above the prompt, redrawn every second:

cache 98% read 80k · wrote 1k · new 300 · 3:41 · 5m · warm: keep going
cache  0% read 0 · wrote 52k · new 300 · 4:58 · 5m · cache missed: model changed
cache 98% read 150k · wrote 1k · new 300 · 0:00 · 5m · expired: the next message rewrites 151k tokens
Enter fullscreen mode Exit fullscreen mode

Three numbers per request, which is how the API reports a prompt: what the cache served, what this request wrote into it, and what went past it uncached. Then a countdown, the lifetime in force, and a verdict.

The verdict is the part that earns its row. “Keep going” means a reply now is a cache read. “Expired” with a large prefix means the next message is a cache write at 1.25x base input, and the Mod says /compact instead, or /clear if you are done with the task anyway.

When it misses, it names why: the model changed, the entry lapsed, or the prefix changed. A prefix change is anything the request is built on top of, so switching model or effort, changing your tool set, or editing CLAUDE.md all land in that bucket.

/cache, and the toasts

/cache opens a pane with the time left as a bar that shrinks, green down to yellow below 40% of the lifetime and red from the warning threshold, a stacked read / wrote / new bar for the last request, and a colour coded table with one row per turn. That table is the part I actually read after a long session, because it shows where the misses were.

The toasts fire once per cache entry: at the warning threshold, which is 60 seconds by default, and then again at 10, 3, 2 and 1 seconds. Only for prompts of 20k tokens or more, so a short session never nags you.

Every request that reads the cache refreshes it at no extra cost. That is Anthropic’s rule, not the Mod’s, and it is why the toast says what it says: any message keeps the 5 minute window alive, and the Mod is only telling you the window is closing.

Installing it 

npx claude-code-templates@latest --mod observability/prompt-cache-control
Enter fullscreen mode Exit fullscreen mode

image

It lands in .claude/skills/prompt-cache-control/ and loads as prompt-cache-control@skills-dir. Then /reload-plugins and you have the band.

Mods need Claude Code v2.1.287 or later and are on by default from that version. If you still export CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 from the early access period, drop it, because v2.1.287 and later ignores it. The component page still carries the old 2.1.259 line, and that is on me to fix.

The options worth changing 

{
  "pluginConfigs": {
    "prompt-cache-control@skills-dir": {
      "options": { "warnSeconds": 120, "compactAtTokens": 60000, "status": true }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode
  • ttl: auto, 5m or 1h. Leave it on auto unless you know better than the inference.
  • warnSeconds: when the band turns yellow and the first toast fires. Default 60.
  • compactAtTokens: the prefix size from which an expired cache suggests /compact. Default 100000.
  • band, status, toast: the three surfaces. Band on, status line entry off, toasts on, by default.

One caveat on that 100k default: it is a judgement call, not a figure from Anthropic’s documentation. If your model’s cache writes hurt, lower it.

pluginConfigs is read from user or managed settings only. Project and local entries are ignored, so putting this in a repository's .claude/settings.json does nothing.

How it works out your lifetime

The cache is 5 minutes by default and 1 hour when asked for, and which one you get depends on your account and your environment. The Mod walks the same precedence chain Claude Code does: its own ttl option, then FORCE_PROMPT_CACHING_5M, CLAUDE_CODE_PROMPT_CACHE_TTL, the promptCacheTtl setting, ENABLE_PROMPT_CACHING_1H, and finally the account, which is 1 hour on a subscription inside its plan usage and 5 minutes on usage credits, an API key or a cloud provider.

Then it watches the traffic, which overrules all of that. A cache hit more than 5 minutes after the previous request proves the 1 hour lifetime. A miss between 5 and 60 minutes later, with the same model and a prompt that did not shrink, says the entry lapsed, so 5 minutes. That covers what a Mod cannot read: managed settings, a gateway rewriting the TTL, or a subscription that ran out of plan usage mid session.

The reason it has to infer at all is a gap in the surface. The API names the TTL of each write, and Claude Code’s status line exposes it as prompt_cache.ttl, but the Mod API hands over only the four token counts. If you want the ground truth, run claude -p "hello" --output-format json and read usage.cache_creation.

Where the Mods live

image

You can follow me on my social media:

Top comments (0)