claudeers.
// Claude Plugins

claude-code-cache-warmer

Claude Code mod that keeps the prompt cache warm and shows each refresh's cost and saving

// Claude Plugins[ api ][ web ][ claude ]#claude#claude-code#claude-code-plugin#prompt-caching#plugins◷ MIT$open-sourceupdated about 1 month ago
Actively maintained
96/100
last commit about 1 month ago
last release none
releases 0
open issues 0
// star history

Install with your AI

Paste into Claude Code, Cursor, or any agent — it reads the repo and wires the tool into your project.

Install and set up claude-code-cache-warmer (claude-plugin project) into my current project.
Found on https://claudeers.com/claude-code-cache-warmer
Repo: https://github.com/paulbkim-dev/claude-code-cache-warmer
Homepage/docs: https://blog.paulbkim.dev/cache-warmer/
Detected install method: claude-plugin → /plugin install claude-code-cache-warmer@paulbkim-dev/claude-code-cache-warmer
Category: plugins. Platforms: api, web.
Read the repo's README for exact setup and env vars, then install it and wire it into my project.

Claudeers Health Verdict:
active; community-verified: false. Confirm the source before running anything.
// or install directly (claude-plugin)
/plugin marketplace add paulbkim-dev/claude-code-cache-warmer
/plugin install claude-code-cache-warmer@paulbkim-dev/claude-code-cache-warmer
// or clone
git clone https://github.com/paulbkim-dev/claude-code-cache-warmer

// compatibility

Platformsapi, web
Operating systems—
AI compatibilityclaude
LicenseMIT
Pricingopen-source
LanguageTypeScript

Get your FREE $2.50 API credits to access TickAtlas financial data ↗
Clawd, the Claude Code mascot, in the refreshing, warm, and expired states

cache-warmer

Keeps the Claude Code prompt cache warm during a break, so your next prompt costs less.

Blog post · Website · X

English · 한국어 · 简体中文


What does it do?

Each prompt sends the full conversation to the API. The API keeps the start of the conversation in a prompt cache for 5 minutes or 1 hour. A prompt that reads the cache costs much less and starts faster. After the cache expires, the next prompt writes the full cache again at a higher price.

cache-warmer sends one small refresh shortly before the cache expires, so the cache stays warm. It works like the cache warmer in Pi.

flowchart LR
    subgraph with["With cache-warmer"]
        direction LR
        b1["Prompt"] --> b2["Break"] --> b3["Refresh<br/>keeps the cache"] --> b4["Next prompt<br/>reads the cache"]
    end
    subgraph without["Without cache-warmer"]
        direction LR
        a1["Prompt"] --> a2["Break"] --> a3["Cache expires"] --> a4["Next prompt<br/>writes the cache again"]
    end

Install

claude plugin marketplace add paulbkim-dev/claude-code-cache-warmer
claude plugin install cache-warmer@claude-code-cache-warmer

Restart Claude Code, then type /cache-warmer to open the pane. To stop all warming, run claude plugin disable cache-warmer.


What you see

During a refresh, a band above the prompt shows Clawd, the Claude Code mascot, beside a notice that the mod is resending the cached prompt. It shows the cache time in color (5m cyan, 1h magenta), the refresh interval, and the outcome: yellow while the refresh runs, green when the cache is warm, and red when it expired or failed. A failed refresh names the API error and its status, such as rate_limit 429. During a turn, the band goes 5 seconds after the refresh. In an idle session it stays until your next prompt, with Clawd still after 5 seconds. The pane's main page shows Clawd too.

  • The refresh never enters the conversation. The transcript keeps one notice row per refresh, starting with ☕, and no request sends it to the model.
  • The band has three styles, set on the Configuration page or in the /config row cache-warmer.band: default shows Clawd beside the notice, simplified shows the notice as one line, and off hides the band.
  • Each refresh request starts with [cache-warmer], so a request log or proxy can tell it from your prompts.
  • reduceMotion keeps Clawd still.
  • /cache-warmer preview plays the three states with no refresh.

The pane

/cache-warmer opens and closes a pane with this menu:

Configuration           this session, then defaults for new sessions
Analytics               costs and savings
Debug mode              on or off
  • The pane takes the keyboard when it opens over an empty prompt, with Configuration selected.
  • /cache-warmer on an open pane without the keyboard gives the keyboard back to it; on a pane with the keyboard, it closes the pane.
  • Tab and the arrow keys move between items. Enter opens a page or turns Debug mode on or off. Each page starts with a Back button, and Enter on a setting such as ● 5m ○ 1h moves it to the next option.
  • Escape closes the pane when the pane has focus, or when the prompt is idle and empty.
  • A line below the menu shows the next refresh, or why warming stopped.

Cache time

5 minutes1 hour
Refresh after4m30s54m
Cache write price1.25× input2× input
Warm time when idle, default limit27m30s5h30m
  • The default is 1 hour. Change it under Global on the Configuration page, in the /config row cache-warmer.ttl, or with /cache-warmer 5m or /cache-warmer 1h. The command also sets the current session.
  • The first main-conversation response locks the session's cache time. /clear or a new session unlocks it. While it is locked, the command refuses, and a new default applies to later sessions only.
  • The mod sets CLAUDE_CODE_PROMPT_CACHE_TTL for this Claude Code process, so it overrides promptCacheTtl and the shell. A change applies from the next request, which writes the cache once.
  • FORCE_PROMPT_CACHING_5M=1 keeps the cache at 5 minutes, and the Configuration page says so.
  • A refresh extends both cache times. In a live test on 2026-10-05, it kept a 1-hour cache warm past 60 minutes.
  • A refresh that reads less than half of the prefix counts as expired and stops warming.

When it refreshes

flowchart TD
    due["90% of the cache time is over"] --> rule{"Expected saving<br/>is $0.05 or more?"}
    rule -- No --> skip["No refresh"]
    rule -- Yes --> idle{"Is the session<br/>idle?"}
    idle -- "No, a turn runs" --> send["Refresh"]
    idle -- Yes --> left{"Idle refreshes left?"}
    left -- Yes --> send
    left -- No --> skip

A refresh is due at 90% of the cache time, and it must pass the rule from Pi:

chance of another request before expiry × extra cost to write the prefix again − refresh cost ≥ $0.05

The chance is 100% while a turn runs and 15% while the session is idle. So each model has a break-even prompt size, and a smaller prompt gets no refresh. The stop reason shows both sizes.

While the session is idle, each cache time gets at most its idle limit of refreshes after the last prompt. The limit is 0 to 20, 5 by default, set on the Configuration page or in cache-warmer.idle5m and cache-warmer.idle1h. When the last idle refresh is used, the band warns that warming stopped and shows when the cache expires, until your next prompt. While a turn runs, warming stops 60 minutes after the last prompt, or after two cache times if that is longer.

Warming also stops after compaction, /clear, a model change, a failed or expired refresh, or a timer that fired too late. The next request starts it again.


Debug mode

While debug mode is on, the newest refreshes show under the menu with their age, result, tokens, cost, and estimated saving. The mod also appends one JSON line per refresh and per stop to <config>/cache-warmer/debug/<session id>.jsonl, where <config> is CLAUDE_CONFIG_DIR or ~/.claude.

⚠️ The mod cannot see /rewind. After a rewind, refreshes keep the later prefix warm until the next request.


What it sends and stores

The mod sends each refresh automatically. Each refresh is a fork of the main conversation's last request, sent to the same model with this prompt:

[cache-warmer] Automated prompt cache refresh by the cache-warmer plugin, not a message from the user. Reply with the single word ok.

SendsOnly the refresh requests. No other network requests and no telemetry.
BillsEach refresh counts against your Claude plan or API key, like any request.
SetsCLAUDE_CODE_PROMPT_CACHE_TTL for the running Claude Code process
StoresAll-time totals in the plugin store, one notice row per refresh in the transcript, and the debug log while debug mode is on
StopsSet both idle limits to 0 to stop idle refreshes. Disable the plugin to stop all refreshes.

Credits

The refresh timing, the $0.05 rule, and the idea of an idle limit come from the cache warmer in Pi by Mario Zechner. cache-warmer ports them to a Claude Code mod and counts idle refreshes instead of stopping at 30 minutes. It copies no Pi code.

Support

Report problems at github.com/paulbkim-dev/claude-code-cache-warmer/issues. cache-warmer is released under the MIT License.

// faq

What is claude-code-cache-warmer?

Claude Code mod that keeps the prompt cache warm and shows each refresh's cost and saving. It is open-source on GitHub.

Is claude-code-cache-warmer free to use?

claude-code-cache-warmer is open-source under the MIT license, so it is free to use.

What category does claude-code-cache-warmer belong to?

claude-code-cache-warmer is listed under plugins in the Claudeers registry of Claude-compatible tools.

21 views
★ 23 stars
unclaimed
updated about 1 month ago

// embed badge

claude-code-cache-warmer on Claudeers
[![Claudeers](https://claudeers.com/api/badge/claude-code-cache-warmer.svg)](https://claudeers.com/claude-code-cache-warmer)

// retro hit counter

claude-code-cache-warmer hit counter
[![Hits](https://claudeers.com/api/counter/claude-code-cache-warmer.svg)](https://claudeers.com/claude-code-cache-warmer)

// reviews

// guestbook

0/500

// related in Claude Plugins

🔓

A single CLAUDE.md file to improve Claude Code behavior, derived from Andrej Karpathy's observations on LLM coding pitfalls.

// pluginsmultica-ai/★ 230,631[ claude ]
🔓

Claude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explainin…

// pluginsanthropics/⟨Python⟩★ 156,472[ claude ]
🔓

"CLI-Anything: Making ALL Software Agent-Native" -- CLI-Hub: https://clianything.cc/

// pluginsHKUDS/⟨Python⟩★ 58,467◷ Apache-2.0[ claude ]
🔓

financial-services — a Claude ecosystem project on GitHub.

// pluginsanthropics/⟨Python⟩★ 41,409◷ Apache-2.0[ claude ]
→ see how claude-code-cache-warmer connects across the ecosystem