cache-meter
Shows above the prompt how warm the prompt cache is, what a cache miss would cost to rewrite, context fill, and the session's API-rate cost
newbandcommandtoasttimer
Shows above the prompt how warm the prompt cache is, what a cache miss would cost to rewrite, context fill, and the session's API-rate cost
Part of my portfolio.
Mods for Claude Code that change what it does and what it shows. Each one is a hooks module: it runs inside Claude Code, hooks prompts, tool calls and turns, and draws a line above the prompt or a pane beside the transcript. The five here are deviation-kernel, cache-meter, goal-board, file-tree and idea-agents. All five ship with tests that run without a live session.
| Mod | What it does | Costs anything? |
|---|---|---|
| deviation-kernel | Keeps the assumptions your project refuses in Claude's system prompt on every request, and catches an edit that brings one back at the step where it lands. | One small Haiku call after each long answer (can be switched off) |
| cache-meter | Shows how long the prompt cache stays warm, what a miss would cost to rewrite, how full the context is, and the session's cost at API rates. | No |
| goal-board | Shows each session's goal, task progress and ETA, and /goals lists every running session on the machine. | No |
| file-tree | Shows the working directory as a file tree in a pane on the right, with folders you open and close and the files Claude just changed marked. | No |
| idea-agents | Gives a project six exploration agents (three that explore ideas, a lazy "trogg" for each) and one ideas/ folder per run, and tells Claude how to run a round. | Only when you run a round: the agents' own model use (the troggs run on Haiku) |
Install any one of them on its own.
Paste this into Claude Code, in a terminal session:
Set up mods from the GitHub repo Spendry/claude-code-mods for me. Work through these steps and stop where a step says to ask me.
1. Run `claude --version`. The mods need 2.1.287 or later; if it's older, tell me how to update and stop.
2. Show me the table of mods from the repo README (https://github.com/Spendry/claude-code-mods) and ask which ones I want. Don't pick for me.
3. Clone https://github.com/Spendry/claude-code-mods into a temporary folder. For each mod I chose, run `claude plugin validate <that folder>/<mod>`, read its `hooks/register.ts`, and tell me in plain words what it can touch (the `calls:` line lists it). Ask me whether to go ahead.
4. Run `claude plugin marketplace add Spendry/claude-code-mods`, then install each mod I approved with `claude plugin install <mod>@claude-code-mods --scope user`. A note that options are not yet set is expected; the defaults apply until I change them. Delete the temporary clone.
5. Run `claude plugin list` and confirm each one shows as enabled.
6. If I chose deviation-kernel: ask which project it's for, and interview me there for the assumptions that project refuses on purpose. Do not suggest refusals of your own; the point of the kernel is that they come from me. For each one I give you, help me word it, propose tells (words or /regex/ that would show up when it's broken) and an "instead:", then show me the KERNEL.md and write it to the project root only when I say so. Then ask which mode I want (ask, warn or block), explain the difference in one line each, and tell me to type `/kernel mode <mode>` in that project's session to set it.
7. If I chose cache-meter: ask whether I pay API rates or use a subscription, and explain that on a subscription its dollar figures are the API-equivalent, not my bill.
8. Finish with a short list of what I still have to do myself (from the "What only you can do" section of the README).Claude runs the install. It can't decide your project's refusals or see the bands for you; that part stays yours.
KERNEL.md. Claude can help you word a refusal and suggest tells, but which assumptions to refuse is your design decision. Start with two or three. You can add more later with /kernel add.## Exempt in KERNEL.md (for example - ideas/**) so the guard skips them; code everywhere else stays checked./kernel log shows what tripped and what you decided./goals and /cache answer in text instead.cache-meter/hooks/register.ts with the date they were checked. A model not in the table is priced at the first row's rates and shown with ≈.At the prompt of a Claude Code terminal session, one line per mod:
/plugin install deviation-kernel --marketplace Spendry/claude-code-mods
/plugin install cache-meter --marketplace Spendry/claude-code-mods
/plugin install goal-board --marketplace Spendry/claude-code-mods
/plugin install file-tree --marketplace Spendry/claude-code-mods
/plugin install idea-agents --marketplace Spendry/claude-code-modsAnswer y to add the marketplace, then pick the user scope so the mod loads in every session. A mod with options shows a screen to set them. /plugin lists what's active.
To turn every mod off for one session: claude --safe-mode. To update: claude plugin update <mod>@claude-code-mods, then /reload-plugins.
Built and tested against Claude Code 2.1.296; needs 2.1.287 or later.
What it guarantees: the project's refused assumptions are in Claude's system prompt on every request, with nothing to paste and nothing lost to compaction. An edit that brings one back is caught at that step.
The problem it answers: a design that refuses a standard assumption tends to lose that refusal while the ordinary parts get filled in. Claude reaches for the conventional component in each slot, and the conventional component carries the assumption the design rejected.
Setup. Put a KERNEL.md at the project root (or .claude/KERNEL.md). /kernel init writes a template; KERNEL.example.md shows a filled-in one. Each refusal is one line:
- R1: one global clock paces every stage | tells: global clock, clock tree, /clk_?en/ | instead: each stage hands off by local request/acknowledgeIn a folder with no kernel, the first prompt you type there asks whether Claude should help you write one: now, after that message, not this session, or never in that folder. Mid-project, Claude reads the project's own record first so its questions point at what you set out to do, then asks you for the refusals (it proposes none of its own) and writes KERNEL.md only when you say so. Your home folder is never asked. Turn the offer off with the offerKernel option.
What happens.
ask (default): holds the edit and asks you. Refusing sends Claude the refusal and its instead:.warn: lets it through and flags it to Claude with your next prompt.block: refuses the edit outright.drop in the band if a flag is wrong. Turn this off with the semanticCheck option if you don't want the extra calls.Commands. /kernel opens the kernel and recent trips · /kernel init · /kernel add <text> | tells: a, b | instead: ... · /kernel mode ask|warn|block · /kernel check (a full audit of the conversation so far, served mostly from cache) · /kernel log · /kernel reload.
Limits. Tells are matched as whole words or regexes, so a tell also fires on a line that rejects the assumption ("no central scheduler"). The semantic check tells the two apart; the keyword check does not. The kernel file is never edited by Claude unless you ask.
What it guarantees: you can see how long the cached prefix has left, what a miss would cost to rewrite, context fill and session cost, without asking.
cache ▰▰▰▰▱▱▱▱ 2:41 · miss $0.50 · ctx 84k/200k 42% · session $4.10 API/cache gives the full breakdown, including the hit and miss price of the next request.cacheTtl option defaults to auto. It assumes the 5-minute cache until a request reads from cache after more than five idle minutes, which only the 1-hour cache can serve. It then switches to 1h, toasts once, and remembers that for later sessions. The rewrite price changes with it (1.25x input for 5m, 2x for 1h). Set 5m or 1h to fix it.hooks/register.ts. On a subscription the dollar figures are what the same work would cost at API rates, not what you're billed.What it guarantees: each session shows its goal, task progress and ETA, and one command shows every running session on this machine.
/goal <text>. /goal clear resets it./goals opens the board of all sessions: working, idle or done, the current task, and the ETA.What it guarantees: you can see the project's files while Claude works on them, and which ones it has changed this session.
╭──────────────────────────────────────────╮
│ work ‹ up home refresh collapse │
│ ──────────────────────────────────────── │
│ ├─ ▸ notes │
│ └─ ▾ relay · here │
│ ├─ ▾ src │
│ │ ├─ ● main.ts │
│ │ └─ util.ts │
│ └─ README.md │
│ │
│ 1 changed · 1 up from relay │
╰──────────────────────────────────────────╯/files opens it (above the prompt on the main screen). /files again closes it.r refreshes and c collapses every folder.‹ up (or u) moves the tree's root up one folder per press, like cd .., until it reaches the drive or filesystem root. The working folder stays open under its parent and is marked · here. home (or h) puts the root back on the working folder. Only the view moves; Claude's working directory stays where it was.background is the hex color painted behind the tree; the default #0f0f0f is half of Windows Terminal's Dark+ background. Set it to half of your own terminal's background, or leave it empty to keep the terminal's. coverFrame (on by default) draws the orange border over Claude Code's own square pane frame, so the side facing the conversation is orange; Claude Code still shows its thin grey line along the top. Turn it off to draw the border just inside the frame instead.…: a file or folder name keeps its start, the path in the footer keeps its end.●. A folder holding one has its name in green, so a change inside a closed folder still shows.duel option..git, node_modules, __pycache__, .venv, venv and .next are left out. A tree is cut at 1,500 rows; close a folder to see the rest.What it guarantees: a project can get a second set of eyes on a stuck problem, from agents that propose and size ideas but never touch its code, with every run kept in its own folder you can read later.
premise-breaker lists the assumptions under a problem and flips each one. field-crosser brings mechanisms from other fields, at least half outside computing. idea-sizer checks the ideas against numbers the project already measured and gives each a kill test. Each has a lazy helper on Haiku, a "trogg": Skip asks "why do it at all?", Borrow "what already does this?", Poke "what's the dumbest quick try?". The upper agents read their trogg's note and say in one line what they took..claude/agents/. It never overwrites an agent the project already has. Then it asks whether Claude should tailor them to the project (its building blocks, gates, results files); Claude shows each change and writes it only when you say so. Home folders and folders you said never for are skipped./ideas new <topic> makes ideas/<date>-<nn>-<topic>/ (or under research/ideas/ if the project keeps research apart, or .claude/agents/ideas/ if that folder exists, to keep runs beside the agents) with a run card (README.md: question, read order, outcome, decisions) and 0-data.md to fill. The agents write 1-premises.md, 2-fields.md, 3-sizing.md and their lazy notes next to it; the main session writes 4-result.md./ideas shows what's installed and the latest run. /ideas install adds missing agents. /ideas tailor starts the tailoring.Each mod is a folder with .claude-plugin/plugin.json, hooks/hooks.json, hooks/register.ts (or .tsx for a mod that draws a pane) and tests/. The marketplace file at .claude-plugin/marketplace.json lists them.
claude plugin validate <mod folder> reports what the mod hooks and calls, and anything the engine would refuse.claude plugin test <mod folder> runs its tests without a session.claude plugin marketplace add <path to clone>) and install from it. A folder marketplace is read from the folder itself, so after an edit /reload-plugins picks up the change with no reinstall.A new mod is a new folder plus one entry in marketplace.json.
MIT. See LICENSE.
hooks/register.ts 207 lines1import type { Register } from 'claude-code'
2
3// Claude API list prices, USD per million tokens, from Anthropic's pricing page as of Oct 2026.
4// Check https://platform.claude.com/docs/en/about-claude/pricing and edit if they move.
5// Cache writes are priced from `input`: 1.25x for the 5-minute cache, 2x for the 1-hour cache.
6type Rate = { input: number; output: number; cacheRead: number }
7const PRICES: { match: RegExp; name: string; rate: Rate }[] = [
8 { match: /opus-5-5/, name: 'Opus 5.5', rate: { input: 4, output: 20, cacheRead: 0.2 } },
9 { match: /sonnet-5-5/, name: 'Sonnet 5.5', rate: { input: 2, output: 10, cacheRead: 0.2 } },
10 { match: /sonnet-5(?!-)/, name: 'Sonnet 5', rate: { input: 2, output: 10, cacheRead: 0.2 } },
11 { match: /haiku-5-5/, name: 'Haiku 5.5', rate: { input: 0.1, output: 0.5, cacheRead: 0.01 } },
12 { match: /haiku-4-5/, name: 'Haiku 4.5', rate: { input: 1, output: 5, cacheRead: 0.1 } },
13]
14// Unknown models (Fable, Mythos, anything newer) fall back to Opus 5.5 rates and show "≈".
15const FALLBACK = PRICES[0]!
16
17type Last = {
18 at: number
19 model: string
20 prefix: number // tokens in the prompt the cache holds: read + written + uncached input
21 read: number
22 wrote: number
23}
24
25const FIVE_MIN = 5 * 60_000
26const ONE_HOUR = 60 * 60_000
27
28// The API usage a mod sees does not say which cache lifetime was written. In `auto`, the meter
29// assumes 5 minutes until a request reads from cache after more than five idle minutes, which
30// only the one-hour cache can serve, and then remembers 1h for every later session.
31let ttlSetting: 'auto' | '5m' | '1h' = 'auto'
32let isDetected = false
33let ttlMs = FIVE_MIN
34let writeMultiplier = 1.25
35
36function applyTtl(isOneHour: boolean) {
37 ttlMs = isOneHour ? ONE_HOUR : FIVE_MIN
38 writeMultiplier = isOneHour ? 2 : 1.25
39}
40
41function ttlLabel(): string {
42 const label = ttlMs >= ONE_HOUR ? '1h' : '5m'
43 if (ttlSetting !== 'auto') return label
44 return isDetected ? `${label}, detected` : `${label}, assumed`
45}
46let warn = true
47
48let last: Last | null = null
49let warnedFor = 0 // the `at` of the request we already warned about
50let isWorking = false
51let context: { tokens?: number; window: number; percent?: number } | null = null
52let costUsd: number | undefined
53
54function priceFor(model: string) {
55 const hit = PRICES.find(p => p.match.test(model))
56 return { ...(hit ?? FALLBACK), isGuess: !hit }
57}
58
59function money(usd: number): string {
60 if (usd < 0.01) return '<$0.01'
61 if (usd < 10) return `$${usd.toFixed(2)}`
62 return `$${usd.toFixed(0)}`
63}
64
65function tokens(n: number): string {
66 return n >= 1000 ? `${Math.round(n / 1000)}k` : String(n)
67}
68
69function clock(ms: number): string {
70 const s = Math.max(0, Math.ceil(ms / 1000))
71 return s >= 3600 ? `${Math.floor(s / 3600)}h${String(Math.floor((s % 3600) / 60)).padStart(2, '0')}` : `${Math.floor(s / 60)}:${String(s % 60).padStart(2, '0')}`
72}
73
74function rewriteCost(l: Last): { usd: number; isGuess: boolean } {
75 const p = priceFor(l.model)
76 return { usd: (l.prefix / 1e6) * p.rate.input * writeMultiplier, isGuess: p.isGuess }
77}
78
79function bar(fraction: number, width = 8): string {
80 const full = Math.round(Math.max(0, Math.min(1, fraction)) * width)
81 return '▰'.repeat(full) + '▱'.repeat(width - full)
82}
83
84async function refreshUsage($: any) {
85 try {
86 const u = await $.session.usage()
87 context = u.context
88 costUsd = u.cost?.usd
89 } catch {
90 // usage figures are optional; the meter still runs on its own counts
91 }
92}
93
94export const register: Register = (on, options) => {
95 const o = (options as { cacheTtl?: string; warnBeforeExpiry?: boolean }) ?? {}
96 ttlSetting = o.cacheTtl === '5m' || o.cacheTtl === '1h' ? o.cacheTtl : 'auto'
97 applyTtl(ttlSetting === '1h')
98 warn = o.warnBeforeExpiry !== false
99
100 on('session.start', async ($, e, next) => {
101 if (ttlSetting === 'auto' && (await $.store.get('detectedTtl')) === '1h') {
102 isDetected = true
103 applyTtl(true)
104 }
105 await refreshUsage($)
106 // Redraw once a second so the countdown moves; the engine throttles and coalesces.
107 $.clock.every(1000, async () => {
108 if (!last) return
109 const left = last.at + ttlMs - (await $.clock.now())
110 if (warn && !isWorking && left > 0 && left <= 60_000 && warnedFor !== last.at) {
111 warnedFor = last.at
112 $.ui.toast(`Cache goes cold in ${clock(left)}. A miss rewrites ${tokens(last.prefix)} tokens ≈ ${money(rewriteCost(last).usd)} at API rates.`, { timeoutMs: 8000 })
113 }
114 $.ui.invalidate('ui.render')
115 })
116 try {
117 await $.command.register({ name: 'cache', description: 'Prompt cache: warmth, rewrite cost, context and session cost', immediate: true })
118 } catch {
119 // name taken
120 }
121 return next(e)
122 })
123
124 on('turn.start', async ($, e, next) => {
125 isWorking = true
126 return next(e)
127 })
128
129 // Every request to the model: what it read from cache, what it wrote, how big the prefix is.
130 on('turn.step', async function* ($, e, next) {
131 const result = yield* next(e)
132 if (!e.agentId && result.usage) {
133 const u = result.usage
134 const at = await $.clock.now()
135 // At least half the previous prefix, so a small shared piece kept warm by another request doesn't count.
136 if (ttlSetting === 'auto' && !isDetected && last && at - last.at > FIVE_MIN && u.cache_read_input_tokens >= last.prefix / 2) {
137 isDetected = true
138 applyTtl(true)
139 await $.store.set('detectedTtl', '1h')
140 $.ui.toast('cache-meter: a cache read after more than 5 idle minutes means the 1-hour cache. The countdown now uses 1h.', { timeoutMs: 8000 })
141 }
142 last = {
143 at,
144 model: u.model || e.model,
145 prefix: u.cache_read_input_tokens + u.cache_creation_input_tokens + u.input_tokens,
146 read: u.cache_read_input_tokens,
147 wrote: u.cache_creation_input_tokens,
148 }
149 await refreshUsage($)
150 $.ui.invalidate('ui.render')
151 }
152 return result
153 })
154
155 on('turn.complete', async ($, e, next) => {
156 if (!e.agentId) isWorking = false
157 await refreshUsage($)
158 $.ui.invalidate('ui.render')
159 return next(e)
160 })
161
162 on('command.run', { command: 'cache' }, async ($) => {
163 await refreshUsage($)
164 if (!last) return { text: 'No requests yet this session, so nothing is cached.' }
165 const left = last.at + ttlMs - (await $.clock.now())
166 const p = priceFor(last.model)
167 const miss = rewriteCost(last)
168 const hitCost = (last.prefix / 1e6) * p.rate.cacheRead
169 const lines = [
170 `Cache: ${left > 0 ? `warm, ${clock(left)} left of ${ttlLabel()}` : 'cold, the next request rewrites the prefix'}`,
171 `Prefix: ${tokens(last.prefix)} tokens (last request read ${tokens(last.read)}, wrote ${tokens(last.wrote)})`,
172 `Next request at API rates (${p.name}${p.isGuess ? ', guessed' : ''}): hit ≈ ${money(hitCost)}, miss ≈ ${money(miss.usd)}`,
173 context ? `Context: ${context.tokens !== undefined ? tokens(context.tokens) : '?'} / ${tokens(context.window)}${context.percent !== undefined ? ` (${Math.round(context.percent)}%)` : ''}` : '',
174 costUsd !== undefined ? `Session so far at API rates: ${money(costUsd)}` : '',
175 ]
176 return { text: lines.filter(Boolean).join('\n') }
177 })
178
179 on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
180 if (!last || e.props.hasSurvey) return next(e)
181 const { Box, Text } = $.ui.resolve(e)
182 const left = last.at + ttlMs - (await $.clock.now())
183 const miss = rewriteCost(last)
184 const approx = miss.isGuess ? '≈' : ''
185
186 const parts: any[] = []
187 if (isWorking) {
188 parts.push(Text({ color: 'green', children: ['cache live'] }))
189 } else if (left > 0) {
190 const f = left / ttlMs
191 const color = f > 0.5 ? 'green' : f > 0.2 ? 'yellow' : 'red'
192 parts.push(Text({ color, children: [`cache ${bar(f)} ${clock(left)}`] }))
193 } else {
194 parts.push(Text({ color: 'red', bold: true, children: ['cache cold'] }))
195 }
196 parts.push(Text({ dimColor: true, children: [` · ${left > 0 || isWorking ? 'miss' : 'next turn'} ${approx}${money(miss.usd)}`] }))
197 if (context) {
198 const pct = context.percent !== undefined ? ` ${Math.round(context.percent)}%` : ''
199 parts.push(Text({ dimColor: true, children: [` · ctx ${context.tokens !== undefined ? tokens(context.tokens) : '?'}/${tokens(context.window)}${pct}`] }))
200 }
201 if (costUsd !== undefined) parts.push(Text({ dimColor: true, children: [` · session ${money(costUsd)} API`] }))
202
203 const theirs = await next(e)
204 return Box({ flexDirection: 'column', children: [Box({ flexDirection: 'row', children: parts }), ...(theirs ? [theirs] : [])] })
205 })
206}
207