cache-warm
Keeps the prompt cache warm on idle chats with a capped fork ping, and tracks cache hits and misses
newcommandpromptmodeltimer
Keeps the prompt cache warm on idle chats with a capped fork ping, and tracks cache hits and misses
Six mods for Claude Code: a one-line status bar, image previews for pasted screenshots, boxed cards for tool calls, a keepalive for the prompt cache, a weekly calendar of your sessions, and animated diagrams Claude can draw in the transcript.
Mods are Claude Code plugins built from function hooks. They need Claude Code 2.1.287 or newer. Mods are an early-access feature: the hooks API can change between releases.
| Mod | What it does |
|---|---|
slick-bar | Replaces the hint line under the prompt with a one-line bar: model, effort, folder, branch, context gauge, prompt-cache health, rate-limit gauges |
image-peek | Shows a preview of a pasted image above the prompt and under the message that sent it |
tool-cards | Draws each tool call as a boxed card: highlighted command, output preview, timing footer |
cache-warm | Keeps the prompt cache of an idle chat warm with a small capped ping, and counts cache hits and misses |
week-calendar | /week draws a calendar of the week's sessions with commits, hours per project, and a 3-line report |
diagram-mod | Gives Claude a show_diagram tool: animated diagrams that play a story step by step, with packets, gauges and a live log |
git clone https://github.com/mustafa89/my-claude-code-mods.git ~/.claude/modsenv block of ~/.claude/settings.json (paths separated by :; ~ is allowed): {
"env": {
"CLAUDE_CODE_PLUGIN_DIRS": "~/.claude/mods/slick-bar:~/.claude/mods/image-peek:~/.claude/mods/tool-cards:~/.claude/mods/cache-warm:~/.claude/mods/week-calendar:~/.claude/mods/diagram-mod"
}
}Leave out the mods you do not want. slick-bar lists cache-warm as a dependency for its cache segment, so load the two together.
<name>: loaded in the transcript.To try one mod for a single session only:
claude --plugin-dir ~/.claude/mods/slick-barIf you use a statusLine command, the bar does not replace it. The bar sits on the hint line under the prompt; your status line stays below it. Remove statusLine from your settings if you want only the bar.
One line under the prompt, after Claude Code's own permission-mode label:
✻ Opus 5.5 1M · medium. The ✻ turns into ◉ while a turn runs.± when the tree has changes, ↑/↓ for commits ahead of or behind the upstream.↻ 3h12m), and a ┃ tick that marks how much of the window has passed. Usage to the right of the tick means you are using it faster than the window allows; the percentage turns amber when the current pace projects past 100%.cache ● 97% 52m ✗1 ⟳2. The dot is green while the cache is warm, amber in the last minutes before it expires, and ○ cold after. Then the share of the last request served from cache, the time until the cache expires, misses (✗) and keepalive pings (⟳).When the terminal is narrow, segments drop in this order: hint text, 7-day gauge, token count, cache, branch, folder. The model and the context gauge always stay.
The bar needs a Nerd Font for the pill shapes and icons.
Image #3 · 1246×846).image-peek draws real images through the kitty graphics protocol, so it needs a terminal that supports it, such as kitty or Ghostty. Elsewhere it shows the image's label instead.
It also needs macOS: it uses sips to make a smaller copy of each image.
Terminal multiplexers: inside a multiplexer that passes kitty graphics through but identifies itself differently (for example herdr, which reports libghostty), Claude Code turns graphics off. To turn them on, add this to the same env block:
"CLAUDE_CODE_FORCE_TERMINAL_IMAGES": "1"Only do this if your terminal really supports kitty graphics. Otherwise images draw as empty boxes.
Every tool call becomes a card:
✓ done, ◌ running, ✗ error, ⊘ interrupted. The command's description follows.+N -M header with a bar shows the size of the change. Narrow terminals stack old over new. A new file from Write keeps Claude Code's own view.▾ output · N lines. JSON is indented; errors show in red.src/cart/total.js:10-30 for a Read.◇ diagram, as wide as the diagram, with the animation inside and ▴ collapse / ▾ expand.Claude Code normally folds runs of reads and searches into one line (Searched for 2 patterns). tool-cards unfolds them, so each call gets its own card.
▾ expand on a card to see all of its output or diff (up to 400 lines). Clicks reach the card in fullscreen mode./cards full expands every card; /cards compact goes back to the preview (5 output lines, 16 diff rows, MCP output folded); /cards switches between the two.Ctrl+o does not expand a card. Claude Code does not tell mods when the Ctrl+o view is open.
Claude Code caches the conversation on the API side. A request that reads the cache pays a small part of the input price; a request after the cache expired writes the whole conversation again. cache-warm sends one small request just before the cache expires, so an idle chat stays warm.
$.model.fork. The fork sends the session's last request again with a one-line prompt. The API reads the conversation from the cache, and that read starts the cache lifetime again. The fork runs no tools and does not show in the transcript.Prompt caching prices, as a multiple of the normal input price:
| Request | Price |
|---|---|
| Cache write, 1-hour cache | 2× |
| Cache write, 5-minute cache | 1.25× |
| Cache read | 0.1× (Opus 5.5: 0.05×, Fable 5.1: 0.025×) |
Example: a 400k-token chat on Opus 5.5 with the 1-hour cache.
A ping costs 1/40 of a cold restart. Four pings cost 80k, one tenth of a restart, even if you never come back to the chat. The keepalive pays for itself when there is a better than 1-in-40 chance that you come back within the next hour. At the general read price of 0.1×, the break-even is 20 pings.
maxPings pings (default 4) per idle stretch. A prompt you type resets the count.| Setting | Values | Default |
|---|---|---|
ttl | 1h, 5m | 1h |
maxPings | a number | 4 |
Change them in /config. Claude Code sessions use the 1-hour cache on most plans. Use 5m for the API default, or when your account runs in usage overage.
/cache-warm status shows the cache state, /cache-warm off stops the pings, /cache-warm on starts them again.
The screenshot shows a real week with every title, project and commit replaced.
/week builds a calendar of this week's Claude Code and Codex sessions, opens it in your browser, and prints a 3-line report:
Shipped: rate limiting, CI runner migration, deploy runbook
Most time: api-service, 22h 27m
Next: Prototype caching layer, Upgrade database driver/week last shows last week; /week -2 goes two weeks back.
git config user.email.bin/build.mjs reads ~/.claude/projects/**/*.jsonl and ~/.codex/sessions/**/*.jsonl, runs git log in each project, and writes one HTML file to ~/.calendar/week-<monday>.html. Node only, no network.The calendar file holds the first message of each session as plain text. It stays on your machine.
~/.calendar/config.json is created on the first run:
| Setting | Default | What it does |
|---|---|---|
dayStartHour | 6 | Work before this hour counts toward the previous day |
gapMinutes | 30 | A gap longer than this starts a new block |
minNoCommitMinutes | 15 | Shorter blocks are not flagged as ending without a commit |
weekStart | mon | mon or sun |
theme | dark | dark or light |
accent, palette | Colours for today, the busiest day, and the projects |
It needs Node and git. It opens the file with open on macOS or xdg-open on Linux.
Ask Claude for a diagram or a visual explanation and it calls the mod's show_diagram tool. The diagram draws in the tool's row in the transcript:
✓ ok, ✗ error, ! warning.meters) that fill in eighths of a cell, and a moving activity wave (spark).side: "left" or "right" becomes a tall panel beside the tree, with rows a step can highlight.Give the spec steps and the diagram plays them in a loop. Each step names the edges carrying traffic (only those light up), changes node statuses, meters and panel highlights, adds log rows, and moves the counters. Meters ease to their new values and counters count up across the step. Without steps, packets loop on the edges you name.
examples/agent-tree.json is the story in the GIF; examples/dispatcher.json is a simple diagram without steps. The bundled skill tells Claude when to use the tool and how to keep a diagram readable: one idea, about 12 nodes at most, labels of 1-3 words, 3-6 steps.
| Setting | Default | What it does |
|---|---|---|
display | inline | inline: the diagram animates in the transcript row. pane: it opens in a side pane, closed with q or Esc (Claude Code only seats a pane it did not ask for from 144 columns) |
Each mod is a folder:
<mod>/
.claude-plugin/plugin.json name, version, description, types
hooks/hooks.json { "modules": ["./register.tsx"] }
hooks/register.tsx the hooks
types/index.d.ts the state the mod keeps
tests/*.test.tsx testsCheck and test a mod:
claude plugin validate ./slick-bar
claude plugin test ./slick-barClaude Code writes the API types into <mod>/.claude-plugin/types/ the first time it loads a mod; those files are not committed. A session started with --plugin-dir reloads a mod when you save its files.
These come from the mods API, not from the mods:
Ctrl+o: tool rows do not report the expanded view (see Expanding output).ttl setting.mcp__<mod>__<tool>, so diagram-mod's tool is mcp__diagram-mod__show_diagram though no MCP server is involved.hooks/register.tsx 176 lines1import { atom, read, update } from 'claude-code'
2import type { EngineInterface, ModelUsage, Register } from 'claude-code'
3
4import type { Health } from '../types'
5
6const TTL_MS: Record<string, number> = { '1h': 3_600_000, '5m': 300_000 }
7
8const health = atom({ plugin: 'cache-warm', key: 'health' } as const, {
9 ttlMs: TTL_MS['1h']!,
10 marginMs: 120_000,
11 maxPings: 4,
12 lastAt: 0,
13 isWarm: false,
14 isEnabled: true,
15 lastRatio: null,
16 hits: 0,
17 misses: 0,
18 pings: 0,
19 pingsTotal: 0,
20 note: '',
21} satisfies Health)
22
23const TICK_MS = 15_000
24// Below this share of the input served from cache, a request counts as a miss.
25const HIT_RATIO = 0.5
26// Requests this small carry no prefix worth caching.
27const MIN_TOKENS = 4_000
28// No pings while the 5h rate-limit window is this full.
29const RATE_LIMIT_PCT = 80
30const PING = 'Keepalive ping, not a task. Reply with the single character: .'
31
32type $ = EngineInterface
33
34function ratio(u: ModelUsage) {
35 const total = u.input_tokens + u.cache_read_input_tokens + u.cache_creation_input_tokens
36 return total >= MIN_TOKENS ? u.cache_read_input_tokens / total : null
37}
38
39// Module variables reset on a reload, which only happens between turns.
40let isBusy = false
41let isPinging = false
42
43async function ping($: $) {
44 isPinging = true
45 try {
46 // The TTL counts from the start of the request that reads the entry.
47 const sentAt = await $.clock.now()
48 const r = await $.model.fork({ prompt: PING })
49 if (!r.isAnswered && r.reason === 'nothing-to-fork') {
50 await update($, health, h => ({ ...h, isWarm: false, note: 'nothing to keep warm' }))
51 return
52 }
53 if (!r.isAnswered) {
54 // The cache was not touched: leave lastAt alone so the next tick retries inside the margin.
55 await update($, health, h => ({ ...h, note: `ping failed: ${r.reason}` }))
56 return
57 }
58 const share = ratio(r.usage)
59 if (share !== null && share < HIT_RATIO) {
60 // The entry had lapsed: this ping paid a full write. Stop until a real turn.
61 await update($, health, h => ({ ...h, isWarm: false, misses: h.misses + 1, note: 'ping missed' }))
62 return
63 }
64 await update($, health, h => ({
65 ...h,
66 lastAt: sentAt,
67 pings: h.pings + 1,
68 pingsTotal: h.pingsTotal + 1,
69 note: 'pinged',
70 }))
71 } finally {
72 isPinging = false
73 }
74}
75
76async function tick($: $) {
77 if (isBusy || isPinging) return
78 const h = await read($, health)
79 if (!h.isEnabled || !h.isWarm || h.lastAt === 0) return
80 const idle = (await $.clock.now()) - h.lastAt
81 // A late timer (sleep, suspend) never pings a cold cache: that would pay a full write.
82 if (idle >= h.ttlMs) {
83 await update($, health, x => ({ ...x, isWarm: false, note: 'expired' }))
84 return
85 }
86 if (idle < h.ttlMs - h.marginMs) return
87 if (h.pings >= h.maxPings) {
88 if (h.note !== 'ping cap reached') await update($, health, x => ({ ...x, note: 'ping cap reached' }))
89 return
90 }
91 const fiveHour = (await $.session.usage()).rateLimits.find(l => l.kind === 'five_hour')
92 if (fiveHour !== undefined && fiveHour.percentUsed >= RATE_LIMIT_PCT) {
93 if (h.note !== 'rate limit high') await update($, health, x => ({ ...x, note: 'rate limit high' }))
94 return
95 }
96 await ping($)
97}
98
99export const register: Register = (on, options) => {
100 const ttlMs = TTL_MS[String(options.ttl)] ?? TTL_MS['1h']!
101 // 30s on a 5m cache, 2m on a 1h one: a fork of a large prefix needs the slack.
102 const marginMs = Math.min(120_000, ttlMs / 10)
103 const maxPings = typeof options.maxPings === 'number' ? options.maxPings : 4
104
105 on('session.start', async ($, e, next) => {
106 const result = await next(e)
107 await update($, health, h => ({ ...h, ttlMs, marginMs, maxPings }))
108 await $.command.register({
109 name: 'cache-warm',
110 description: 'Prompt cache keepalive: /cache-warm on | off | status',
111 })
112 $.clock.every(TICK_MS, () => void tick($).catch(() => undefined))
113 return result
114 })
115
116 on('command.run', { command: 'cache-warm' }, async ($, e) => {
117 const arg = e.args.trim()
118 if (arg === 'on' || arg === 'off') await update($, health, h => ({ ...h, isEnabled: arg === 'on' }))
119 const h = await read($, health)
120 const idle = h.lastAt > 0 ? Math.round(((await $.clock.now()) - h.lastAt) / 1000) : null
121 const parts = [
122 `keepalive ${h.isEnabled ? 'on' : 'off'}`,
123 `ttl ${h.ttlMs / 60_000}m`,
124 h.isWarm ? 'warm' : 'cold',
125 idle !== null ? `idle ${idle}s` : 'no request yet',
126 `hits ${h.hits} · misses ${h.misses}`,
127 `pings ${h.pings}/${h.maxPings} (session ${h.pingsTotal})`,
128 h.note,
129 ]
130 return { text: parts.filter(Boolean).join(' · ') }
131 })
132
133 on('prompt.submit', async ($, e, next) => {
134 isBusy = true
135 await update($, health, h => ({ ...h, pings: 0 }))
136 return next(e)
137 })
138
139 // Every main-thread request refreshes the entry; the first of a turn says whether it survived the gap.
140 on('turn.step', async function* ($, e, next) {
141 // Turns start without a typed prompt too (task notices, queued commands).
142 if (e.agentId === undefined && !isPinging) isBusy = true
143 const sentAt = await $.clock.now()
144 const result = yield* next(e)
145 if (e.agentId !== undefined || isPinging || result.usage === null) return result
146 const share = ratio(result.usage)
147 await update($, health, h => {
148 // The session's first request has nothing to hit.
149 const counts = e.index === 0 && share !== null && h.lastAt > 0
150 return {
151 ...h,
152 lastAt: sentAt,
153 isWarm: true,
154 lastRatio: share ?? h.lastRatio,
155 hits: h.hits + (counts && share >= HIT_RATIO ? 1 : 0),
156 misses: h.misses + (counts && share < HIT_RATIO ? 1 : 0),
157 note: '',
158 }
159 })
160 return result
161 })
162
163 on('turn.complete', async ($, e, next) => {
164 const result = await next(e)
165 if (e.agentId === undefined) isBusy = false
166 return result
167 })
168
169 // A compacted transcript is a new prefix: the next request writes it afresh.
170 on('session.compact', async ($, e, next) => {
171 const result = await next(e)
172 await update($, health, h => ({ ...h, isWarm: false, note: 'compacted' }))
173 return result
174 })
175}
176types/index.d.ts 29 lines1export type Health = {
2 /** Cache lifetime and how long before expiry a ping goes out, in ms. */
3 ttlMs: number
4 marginMs: number
5 /** Pings per idle stretch before the cache is left to expire. */
6 maxPings: number
7 /** When the last request that read or wrote the cache finished; 0 before the first. */
8 lastAt: number
9 isWarm: boolean
10 isEnabled: boolean
11 /** Share of the last main-thread request's input the cache served, 0..1. */
12 lastRatio: number | null
13 hits: number
14 misses: number
15 /** Pings in the current idle stretch, and over the session. */
16 pings: number
17 pingsTotal: number
18 /** Why pinging stopped or what the last ping did. */
19 note: string
20}
21
22declare module 'claude-code' {
23 interface PluginState {
24 'cache-warm': {
25 health: Health
26 }
27 }
28}
29