Token Weather
A live forecast of the context window, drawn above the prompt.
newband
A live forecast of the context window, drawn 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 119 lines1import { atom, read, update } from 'claude-code'
2import type { EngineInterface, Register } from 'claude-code'
3
4import type { TokenWeatherReading } from '../types'
5
6const HISTORY = 12
7const BARS = '▁▂▃▄▅▆▇█'
8const FORECAST = [
9 { upTo: 25, icon: '☀', word: 'Clear', color: 'yellow' },
10 { upTo: 50, icon: '☁', word: 'Cloudy', color: 'cyan' },
11 { upTo: 75, icon: '☂', word: 'Showers', color: 'blue' },
12 { upTo: 90, icon: '☇', word: 'Storm', color: 'magenta' },
13 { upTo: Infinity, icon: '↯', word: 'Compact soon', color: 'red' },
14] as const
15
16// Held by the host, so the history survives a hot reload of this file.
17const readings = atom({ plugin: 'token-weather', key: 'readings' } as const, [])
18
19export const register: Register = on => {
20 on('session.start', async ($, e, next) => {
21 const result = await next(e)
22 await takeReading($)
23
24 return result
25 })
26
27 on('turn.complete', async ($, e, next) => {
28 const result = await next(e)
29
30 // Main-loop turns only, not subagents.
31 if (!e.agentId) {
32 await takeReading($)
33 }
34
35 return result
36 })
37
38 on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
39 const history = await read($, readings)
40 const now = history.at(-1)
41
42 if (e.props.hasSurvey || now === undefined) {
43 return next(e)
44 }
45
46 const { Box, Text } = $.ui.resolve(e)
47 const prev = history.at(-2)
48 const f = FORECAST.find(b => now.percent < b.upTo) ?? FORECAST[4]
49 const head = `${f.icon} ${f.word}`
50 const percent = ` ${now.percent}% of context`
51 const size = ` ${short(now.tokens)} / ${short(now.window)}`
52 const spark = sparkline(history)
53 const change = prev ? trend(now.tokens - prev.tokens) : ''
54 // Add the history only when the whole row fits the band, so it does not wrap.
55 const room = e.props.bodyColumns - 2
56 const isWide = (head + percent + size + ' last turns ' + spark + change).length <= room
57 const hasSize = (head + percent + size).length <= room
58 // Stack above whatever the plugins beneath draw, so other bands stay.
59 const below = await next(e)
60
61 return (
62 <Box flexDirection="column">
63 <Box flexDirection="row" paddingX={1}>
64 <Text color={f.color} bold>
65 {head}
66 </Text>
67 <Text wrap="truncate-end">{percent}</Text>
68 {hasSize && <Text dimColor>{size}</Text>}
69 {isWide && <Text dimColor>{' last turns '}</Text>}
70 {isWide && <Text color={f.color}>{spark}</Text>}
71 {isWide && prev && <Text dimColor>{change}</Text>}
72 </Box>
73 {below}
74 </Box>
75 )
76 })
77}
78
79async function takeReading($: EngineInterface) {
80 const { context } = await $.session.usage()
81
82 if (!context?.window || context.tokens === undefined) {
83 return
84 }
85
86 const reading: TokenWeatherReading = {
87 tokens: context.tokens,
88 window: context.window,
89 percent: context.percent ?? Math.round((context.tokens / context.window) * 100),
90 }
91 await update($, readings, history => [...(history ?? []), reading].slice(-HISTORY))
92}
93
94function sparkline(history: readonly TokenWeatherReading[]) {
95 const top = Math.max(...history.map(r => r.tokens), 1)
96
97 return history.map(r => BARS[Math.floor((r.tokens / top) * (BARS.length - 1))]).join('')
98}
99
100function trend(delta: number) {
101 if (delta === 0) {
102 return ' steady'
103 }
104
105 return delta > 0 ? ` ▲ +${short(delta)} last turn` : ` ▼ ${short(-delta)} last turn`
106}
107
108function short(n: number) {
109 if (n >= 1_000_000) {
110 return `${+(n / 1_000_000).toFixed(1)}M`
111 }
112
113 if (n >= 1_000) {
114 return `${+(n / 1_000).toFixed(1)}k`
115 }
116
117 return String(n)
118}
119types/index.d.ts 8 lines1export type TokenWeatherReading = { tokens: number; window: number; percent: number }
2
3declare module 'claude-code' {
4 interface PluginState {
5 'token-weather': { readings: TokenWeatherReading[] }
6 }
7}
8