Cache Clock
Counts down to the prompt cache going cold, with the last request's hit rate, above the prompt.
newbandtimer
Counts down to the prompt cache going cold, with the last request's hit rate, above the prompt.
Live panes, prompt bands, status line entries, toasts, and hooks for Claude Code, each shipped as a plugin.
/plugin marketplace add tartinerlabs/claude-code-mods
/plugin install <mod> --marketplace tartinerlabs/claude-code-mods| | Mod | Where it shows | In one line | | :-: | --- | --- | --- | | ⏸ | auto-resume | Status line, toast | Picks a turn back up once a usage limit resets | | 🏷 | auto-session-name | Session title | Names each session from its first prompt | | ⏱ | cache-clock | Band above the prompt | Counts down to the prompt cache going cold | | 📊 | limit-watch | Band above the prompt, toasts | Shows the 5-hour and weekly usage limits | | 🛫 | pr-pilot | Band above the prompt, toasts | Shows the branch's PR checks and merges it with /merge | | 🗜 | smart-compact | Toast | Compacts between turns, sooner at checkpoints or when the cache is cooling | | ⛅ | token-weather | Band above the prompt | Forecasts how full the context window is |
When a turn stops on a usage limit, waits until the limit resets and sends continue. Typing a prompt yourself or running /auto-resume cancel stops the wait.
⏸ auto-resume in 1h 12m ← status line
Usage limit reset, resuming ← toast<sub>📁 plugins/auto-resume</sub>
Names each session from its first prompt using Haiku and can give it a prompt bar colour, so it is easy to find with claude -r after a crash. Sessions already named with -n or /rename are left alone. Set the color option to red, blue, green, yellow, purple, orange, pink or cyan to colour named sessions; default leaves the colour alone.
> fix the flaky retry test in the upload worker
→ session titled "Fix flaky upload retry test"<sub>📁 plugins/auto-session-name</sub>
Draws a countdown above the prompt to when the prompt cache goes cold, with the last request's hit rate. Once cold, it shows how much the next turn re-writes. Set the ttl option to 1h when extended caching is on.
cache ● 3:42 left · 96% hit ← green, yellow under a minute
cache ○ cold · next turn re-writes 84.3k ← red<sub>📁 plugins/cache-clock</sub>
Draws the 5-hour and weekly usage limits above the prompt with live reset countdowns, green under 60%, yellow to 80% and red past it. Toasts once a window passes 80% and again at 95%. Any other window the API reports, such as a gateway spend limit, shows under its own name.
5h 42% · 2h17m 7d 81% · 3d4h ← band
7d limit at 81%, resets in 3d4h ← toast<sub>📁 plugins/limit-watch</sub>
Draws the current branch's open pull request above the prompt with its checks and whether it can merge, refreshed each minute and after every turn. Toasts when a run of checks finishes. /merge merges it with gh and deletes the branch, but only once every check has passed and nothing blocks it. On a gh-stack layer the band shows its place in the stack, and /merge merges the whole stack with gh stack merge once every unmerged layer has passed its checks and has no unpushed commits, then switches to the trunk and deletes every layer's branch, local and remote, once all of them have merged. Set the method option to merge (default), squash or rebase. Needs the GitHub CLI, signed in.
PR #42 ◐ 3/5 checks waiting ← band
PR #42 ✗ 1 failing: SonarCloud blocked ← red
PR #42 ✓ 5/5 checks ready · /merge ← green
PR #42 stack 2/3 ✓ 5/5 checks ready · /merge ← a gh-stack layer
PR #42 checks passed, ready to /merge ← toast<sub>📁 plugins/pr-pilot</sub>
Compacts the conversation between turns, never during one, weighing several factors against the context's fill. Past the threshold option (60, 70 default, or 80%) it compacts about ten seconds after a turn ends. It compacts sooner when compacting is cheapest or most worth it:
gh pr, gh stack), had a plan approved, finished its todo list, or switched branch or worktree. The summary is told what to keep for each, such as the approved plan verbatim. A checkpoint counts only until the next turn starts. Set checkpoints to off to ignore them.Nothing takes it under the floor option (30, 40 default, or 50%), and it tries at most once per idle stretch. Set ttl to 1h when extended prompt caching is on.
Compacted at 52%: committed ← toast
Compacted at 55%: cache cooling ← toast
Compacted at 74%: context high, 5h limit at 86% ← toast<sub>📁 plugins/smart-compact</sub>
Draws a forecast of the context window above the prompt, with tokens used, a sparkline of the last 12 turns and the change since the last turn.
☁ Cloudy 38% of context 76.4k / 200k last turns ▁▂▂▃▄▄▅▆ ▲ +4.1k last turn| ☀ Clear | ☁ Cloudy | ☂ Showers | ☇ Storm | ↯ Compact soon | | :-: | :-: | :-: | :-: | :-: | | under 25% | under 50% | under 75% | under 90% | 90% and up |
<sub>📁 plugins/token-weather</sub>
hooks/register.tsx 101 lines1import { atom, read, update } from 'claude-code'
2import type { Register } from 'claude-code'
3
4import type { CacheClockReading } from '../types'
5
6const TTL_MS = { '5m': 5 * 60_000, '1h': 60 * 60_000 } as const
7
8// Held by the host, so the countdown survives a hot reload of this file.
9const last = atom({ plugin: 'cache-clock', key: 'last' } as const, null)
10
11export const register: Register = (on, options) => {
12 const ttlMs = options.ttl === '1h' ? TTL_MS['1h'] : TTL_MS['5m']
13
14 on('session.start', async ($, e, next) => {
15 const result = await next(e)
16 // Redraw the band each second so the countdown ticks.
17 $.clock.every(1000, () => $.ui.invalidate('ui.render'))
18
19 return result
20 })
21
22 on('turn.step', async function* ($, e, next) {
23 const result = yield* next(e)
24
25 // Main-loop requests only: a subagent's cache is its own.
26 if (!e.agentId && result.usage) {
27 const { cache_read_input_tokens, cache_creation_input_tokens, input_tokens, output_tokens } = result.usage
28 const reading: CacheClockReading = {
29 at: await $.clock.now(),
30 read: cache_read_input_tokens,
31 write: cache_creation_input_tokens,
32 input: input_tokens,
33 output: output_tokens,
34 }
35 await update($, last, () => reading)
36 }
37
38 return result
39 })
40
41 on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
42 const reading = await read($, last)
43
44 if (e.props.hasSurvey || reading === null) {
45 return next(e)
46 }
47
48 const { Box, Text } = $.ui.resolve(e)
49 const left = reading.at + ttlMs - (await $.clock.now())
50 const full = describe(reading, left)
51 // On a narrow band keep only the state, so the row does not wrap.
52 const text = full.length <= e.props.bodyColumns - 2 ? full : full.split(' · ')[0]
53 // Stack above whatever the plugins beneath draw, so other bands stay.
54 const below = await next(e)
55
56 return (
57 <Box flexDirection="column">
58 <Box flexDirection="row" paddingX={1}>
59 <Text color={left <= 0 ? 'red' : left < 60_000 ? 'yellow' : 'green'} wrap="truncate-end">
60 {text}
61 </Text>
62 </Box>
63 {below}
64 </Box>
65 )
66 })
67}
68
69export function describe(reading: CacheClockReading, left: number) {
70 if (left <= 0) {
71 // The next request writes the whole prefix again.
72 const prefix = reading.read + reading.write + reading.input + reading.output
73
74 return `cache ○ cold · next turn re-writes ${short(prefix)}`
75 }
76
77 const prompt = reading.read + reading.write + reading.input
78 const hit = prompt === 0 ? 0 : Math.round((reading.read / prompt) * 100)
79
80 return `cache ● ${clock(left)} left · ${hit}% hit`
81}
82
83function clock(ms: number) {
84 const s = Math.ceil(ms / 1000)
85 const m = Math.floor(s / 60)
86
87 return `${m}:${String(s % 60).padStart(2, '0')}`
88}
89
90function short(n: number) {
91 if (n >= 1_000_000) {
92 return `${+(n / 1_000_000).toFixed(1)}M`
93 }
94
95 if (n >= 1_000) {
96 return `${+(n / 1_000).toFixed(1)}k`
97 }
98
99 return String(n)
100}
101types/index.d.ts 8 lines1export type CacheClockReading = { at: number; read: number; write: number; input: number; output: number }
2
3declare module 'claude-code' {
4 interface PluginState {
5 'cache-clock': { last: CacheClockReading | null }
6 }
7}
8