hud

1import { atom, read, update } from 'claude-code'
2import type { EngineInterface, Register, Timer } from 'claude-code'
3
4import type { Git, HudView, Limit } from '../types'
5import { limitsToWarn, limitWarning, parseConfig, parseGit, parseWorktree, rows } from './hud'
6import type { Config } from './hud'
7
8/** How often the colours move while a turn runs. */
9const FRAME_MS = 150
10/** How often the figures are read again while a turn runs, in frames, and while idle. */
11const WORKING_REFRESH_FRAMES = 40
12const IDLE_REFRESH_MS = 30_000
13const GIT_TIMEOUT_MS = 5_000
14/** The row's room where the surface does not say. */
15const DEFAULT_COLUMNS = 100
16
17const EMPTY: HudView = {
18  model: '',
19  effort: null,
20  contextPercent: null,
21  limits: [],
22  costUsd: null,
23  startedAt: 0,
24  git: null,
25  worktree: null,
26  folder: '',
27  agents: 0,
28  toolsTurn: 0,
29  toolsSession: 0,
30  isWorking: false,
31  turnStartedAt: 0,
32}
33const view = atom({ plugin: 'hud', key: 'view' } as const, EMPTY)
34const frame = atom({ plugin: 'hud', key: 'frame' } as const, 0)
35const warned = atom({ plugin: 'hud', key: 'warned' } as const, {} as Record<string, string | null>)
36
37// Die with the module on a reload; session.start, the next attach or the next turn starts them again.
38let moving: Timer | undefined
39let idle: Timer | undefined
40
41/**
42 * Whether any surface shows the session right now. Asked before each action
43 * the mod starts on its own and never kept. Each mod carries its own copy (ADR-0001).
44 */
45async function isShown($: EngineInterface): Promise<boolean> {
46  return (await $.session.surfaces()).length > 0
47}
48
49/** The working tree's state, and the top folder of the worktree the session is in. */
50async function readGit($: EngineInterface): Promise<{ git: Git | null; worktree: string | null }> {
51  const [status, where] = await Promise.all(
52    [
53      ['git', 'status', '--porcelain=v2', '--branch'],
54      ['git', 'rev-parse', '--show-toplevel'],
55    ].map(argv => $.process.run(argv, { timeoutMs: GIT_TIMEOUT_MS }).catch(() => undefined)),
56  )
57  return {
58    git: status === undefined || status.exitCode !== 0 ? null : parseGit(status.stdout),
59    worktree: where === undefined || where.exitCode !== 0 ? null : parseWorktree(where.stdout),
60  }
61}
62
63/**
64 * Toasts each rate limit that has reached the red level, once in its window. The limits due are worked out
65 * inside the update, so two refreshes at once cannot both toast the same one.
66 */
67async function warnLimits($: EngineInterface, limits: readonly Limit[]): Promise<void> {
68  const now = await $.clock.now()
69  let due: Limit[] = []
70  await update($, warned, held => {
71    due = limitsToWarn(limits, held, now)
72    return due.length === 0 ? held : { ...held, ...Object.fromEntries(due.map(limit => [limit.kind, limit.resetsAt])) }
73  })
74  for (const limit of due) $.ui.toast(limitWarning(limit, now))
75}
76
77/** Reads the figures again, and warns of a rate limit in the red. Git costs a process, so it is read only when asked for. */
78async function refresh($: EngineInterface, withGit: boolean): Promise<void> {
79  const [usage, model, folder, agents] = await Promise.all([
80    $.session.usage(),
81    $.session.model().catch(() => ''),
82    $.session.cwd().catch(() => ''),
83    $.agent.list().catch(() => []),
84  ])
85  const repo = withGit ? await readGit($) : undefined
86  const limits = usage.rateLimits.map((limit): Limit => ({ kind: limit.kind, percent: limit.percentUsed, resetsAt: limit.resetsAt ?? null }))
87  await update($, view, (current): HudView => ({
88    ...current,
89    model,
90    folder,
91    contextPercent: usage.context.percent ?? null,
92    limits,
93    costUsd: usage.cost?.usd ?? null,
94    startedAt: usage.startedAt,
95    agents: agents.filter(agent => agent.status === 'running').length,
96    git: repo === undefined ? current.git : repo.git,
97    worktree: repo === undefined ? current.worktree : repo.worktree,
98  }))
99  await warnLimits($, limits)
100}
101
102function stopMoving(): void {
103  moving?.cancel()
104  moving = undefined
105}
106
107function stopIdle(): void {
108  idle?.cancel()
109  idle = undefined
110}
111
112/** Moves the row's colours and its turn timer while a turn runs and a surface shows it; a beat that finds neither stops. */
113function startMoving($: EngineInterface): void {
114  if (moving !== undefined) return
115  const own = $.clock.every(FRAME_MS, () => {
116    void (async () => {
117      if (!(await read($, view)).isWorking || !(await isShown($))) {
118        if (moving === own) stopMoving()
119        return
120      }
121      const beat = (await read($, frame)) + 1
122      await update($, frame, () => beat)
123      if (beat % WORKING_REFRESH_FRAMES === 0) await refresh($, false)
124    })().catch(() => undefined)
125  })
126  moving = own
127}
128
129/** Reads the figures again now and then while nothing else does; a beat that finds no surface stops until the next attach. */
130function startIdle($: EngineInterface): void {
131  if (idle !== undefined) return
132  const own = $.clock.every(IDLE_REFRESH_MS, () => {
133    void (async () => {
134      if (!(await isShown($))) {
135        if (idle === own) stopIdle()
136        return
137      }
138      await refresh($, !(await read($, view)).isWorking)
139      // The session length and the time to a reset move on even when no figure changed.
140      await update($, frame, beat => beat + 1)
141    })().catch(() => undefined)
142  })
143  idle = own
144}
145
146async function wake($: EngineInterface): Promise<void> {
147  if (!(await isShown($))) return
148  startIdle($)
149  await refresh($, true)
150}
151
152export const register: Register = (on, options) => {
153  const config: Config = parseConfig(options)
154
155  on('session.start', async ($, e, next) => {
156    const started = await next(e)
157    stopMoving()
158    stopIdle()
159    // A headless session does nothing until a surface attaches.
160    await wake($).catch(() => undefined)
161    return started
162  })
163
164  on('session.attach', async ($, e, next) => {
165    const attached = await next(e)
166    await wake($).catch(() => undefined)
167    return attached
168  })
169
170  on('turn.start', async ($, e, next) => {
171    if (await isShown($).catch(() => false)) {
172      const now = await $.clock.now()
173      // The event does not say whose turn begins: a subagent starting mid-turn does not restart the count.
174      await update($, view, (current): HudView => (current.isWorking ? current : { ...current, isWorking: true, turnStartedAt: now, toolsTurn: 0 })).catch(() => undefined)
175      if (config.animate || !config.hidden.has('turn')) startMoving($)
176    }
177    return next(e)
178  })
179
180  on('turn.step', async function* ($, e, next) {
181    // The request says how hard it asks the model to think; a subagent's own setting is not the session's.
182    if (e.agentId === undefined) {
183      const effort = e.effort === undefined ? null : String(e.effort)
184      await update($, view, (current): HudView => (current.effort === effort ? current : { ...current, effort })).catch(() => undefined)
185    }
186    // The response streams through untouched.
187    return yield* next(e)
188  })
189
190  on('tool.call', async ($, e, next) => {
191    if (await isShown($).catch(() => false)) {
192      await update($, view, (current): HudView => ({ ...current, toolsTurn: current.toolsTurn + 1, toolsSession: current.toolsSession + 1 })).catch(() => undefined)
193    }
194    return next(e)
195  })
196
197  on('turn.complete', async ($, e, next) => {
198    const done = await next(e)
199    if (e.agentId !== undefined) return done
200    stopMoving()
201    if (await isShown($).catch(() => false)) {
202      await update($, view, (current): HudView => ({ ...current, isWorking: false })).catch(() => undefined)
203      // Awaited: work left running when a hook returns is dropped with its dispatch.
204      await refresh($, true).catch(() => undefined)
205    }
206    return done
207  })
208
209  on('ui.render', { component: 'PromptHint' }, async ($, e, next) => {
210    const beneath = await next(e)
211    if (config.placement !== 'below') return beneath
212    const current = await read($, view)
213    const lines = rows(current, config, await $.clock.now(), await read($, frame), e.viewport?.columns ?? DEFAULT_COLUMNS)
214    if (lines.length === 0) return beneath
215    const { Box, Text } = $.ui.resolve(e)
216
217    return (
218      <Box flexDirection="column">
219        {lines.map((line, at) => (
220          <Box key={`line-${at}`} flexDirection="row" columnGap={2}>
221            {line.map(segment => (
222              <Box key={segment.id} flexDirection="row" columnGap={1}>
223                <Text dimColor>{segment.label}</Text>
224                <Text color={segment.color} bold={segment.isBold} inverse={segment.isInverse}>
225                  {segment.text}
226                </Text>
227              </Box>
228            ))}
229          </Box>
230        ))}
231        {beneath}
232      </Box>
233    )
234  })
235
236  on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
237    const beneath = await next(e)
238    if (config.placement !== 'above' || e.props.hasSurvey || e.props.view.agentId !== undefined) return beneath
239    const current = await read($, view)
240    const lines = rows(current, config, await $.clock.now(), await read($, frame), e.props.bodyColumns)
241    if (lines.length === 0) return beneath
242    const { Box, Text } = $.ui.resolve(e)
243
244    // No width here: the engine refuses its own band under a Box that sets one, and each line is cut to bodyColumns.
245    return (
246      <Box flexDirection="column">
247        {lines.map((line, at) => (
248          <Box key={`line-${at}`} flexDirection="row" columnGap={2}>
249            {line.map(segment => (
250              <Box key={segment.id} flexDirection="row" columnGap={1}>
251                <Text dimColor>{segment.label}</Text>
252                <Text color={segment.color} bold={segment.isBold} inverse={segment.isInverse}>
253                  {segment.text}
254                </Text>
255              </Box>
256            ))}
257          </Box>
258        ))}
259        {beneath}
260      </Box>
261    )
262  })
263}
264

1import type { Git, HudView, Limit } from '../types'
2
3export const SEGMENTS = ['model', 'effort', 'context', 'limits', 'turn', 'tools', 'agents', 'git', 'worktree', 'cost', 'session', 'folder'] as const
4export type SegmentId = (typeof SEGMENTS)[number]
5
6export type Theme = 'neon' | 'ocean' | 'ember' | 'mono'
7export type Config = { theme: Theme; animate: boolean; placement: 'below' | 'above'; hidden: ReadonlySet<SegmentId> }
8
9/** One figure of the row: the label that names it, its text, and how the text is painted. */
10export type Segment = { id: string; kind: SegmentId; label: string; text: string; color: string | undefined; isBold: boolean; isInverse: boolean }
11
12type Level = 'ok' | 'warn' | 'danger'
13
14/** Left out first when the row is too wide; what is not named here goes last. */
15const DROP_ORDER: readonly SegmentId[] = ['folder', 'session', 'cost', 'worktree', 'tools', 'git', 'agents', 'effort', 'model', 'turn', 'limits', 'context']
16const GAP = 2
17const GAUGE_CELLS = 8
18const LEVEL_COLORS: Readonly<Record<Level, string>> = { ok: '#5fff87', warn: '#ffd75f', danger: '#ff5f5f' }
19const PALETTES: Readonly<Record<Theme, readonly string[]>> = {
20  neon: ['#ff5fd7', '#af87ff', '#5fafff', '#5fffd7', '#d7ff5f', '#ffaf5f'],
21  ocean: ['#5fd7ff', '#5fafff', '#5f87ff', '#87afff', '#5fffd7', '#87ffd7'],
22  ember: ['#ffd75f', '#ffaf5f', '#ff875f', '#ff5f5f', '#ff5f87', '#ffaf87'],
23  mono: [],
24}
25/** The worktree figure's label: the leafless tree, then its name. */
26const WORKTREE_LABEL = '\u{1FABE} worktree'
27const LIMIT_NAMES: Readonly<Record<string, string>> = { five_hour: '5h limit', seven_day: '7d limit', spend_limit: 'spend limit' }
28/** The share of a rate limit at which its figure turns yellow, and red. */
29const LIMIT_WARN_AT = 75
30const LIMIT_DANGER_AT = 90
31/** The figures of the first line; the rest go on the second. */
32const FIRST_LINE: ReadonlySet<SegmentId> = new Set(['model', 'effort', 'context', 'limits'])
33
34function isSegment(name: string): name is SegmentId {
35  return (SEGMENTS as readonly string[]).includes(name)
36}
37
38export function parseConfig(options: Readonly<Record<string, unknown>>): Config {
39  const theme = options.theme
40  const hide = typeof options.hide === 'string' ? options.hide : ''
41  return {
42    theme: theme === 'ocean' || theme === 'ember' || theme === 'mono' ? theme : 'neon',
43    animate: options.animate !== false,
44    placement: options.placement === 'above' ? 'above' : 'below',
45    hidden: new Set(hide.split(',').map(name => name.trim().toLowerCase()).filter(isSegment)),
46  }
47}
48
49/** `claude-fable-5-1[1m]` as `fable 5.1`: the family and its version, without the vendor, the date or the window. */
50export function shortModel(model: string): string {
51  const bare = model.replace(/\[.*\]$/, '').replace(/^claude-/, '').replace(/-\d{8}$/, '')
52  const [, family = bare, version = ''] = /^([a-z]+)-(\d+(?:-\d+)*)$/i.exec(bare) ?? []
53  return version === '' ? family : `${family} ${version.replace(/-/g, '.')}`
54}
55
56/** A length of time in its two largest parts: `42s`, `4m 12s`, `1h 6m`, `2d 3h`. */
57export function duration(ms: number): string {
58  const seconds = Math.max(0, Math.floor(ms / 1000))
59  if (seconds < 60) return `${seconds}s`
60  const minutes = Math.floor(seconds / 60)
61  if (minutes < 60) return `${minutes}m ${seconds % 60}s`
62  const hours = Math.floor(minutes / 60)
63  return hours < 24 ? `${hours}h ${minutes % 60}m` : `${Math.floor(hours / 24)}d ${hours % 24}h`
64}
65
66/** A length of time to the minute, for figures that move slowly: `under 1m`, `12m`, `1h 6m`. */
67export function coarse(ms: number): string {
68  const minutes = Math.floor(Math.max(0, ms) / 60_000)
69  if (minutes < 1) return 'under 1m'
70  if (minutes < 60) return `${minutes}m`
71  const hours = Math.floor(minutes / 60)
72  return hours < 24 ? `${hours}h ${minutes % 60}m` : `${Math.floor(hours / 24)}d ${hours % 24}h`
73}
74
75export function gauge(percent: number, cells = GAUGE_CELLS): string {
76  const filled = Math.max(0, Math.min(cells, Math.round((percent / 100) * cells)))
77  return '█'.repeat(filled) + '░'.repeat(cells - filled)
78}
79
80export function level(percent: number, warnAt: number, dangerAt: number): Level {
81  if (percent >= dangerAt) return 'danger'
82  return percent >= warnAt ? 'warn' : 'ok'
83}
84
85/** The last part of a path, whatever its slashes. */
86export function folderName(cwd: string): string {
87  const parts = cwd.split(/[\\/]+/).filter(part => part !== '')
88  return parts[parts.length - 1] ?? cwd
89}
90
91/** Reads `git status --porcelain=v2 --branch`: the branch, commits ahead and behind, and the count of changed files. */
92export function parseGit(output: string): Git | null {
93  const lines = output.split(/\r?\n/)
94  const head = lines.find(line => line.startsWith('# branch.head '))
95  if (head === undefined) return null
96  const [, ahead = '0', behind = '0'] = /^# branch\.ab \+(\d+) -(\d+)/.exec(lines.find(line => line.startsWith('# branch.ab ')) ?? '') ?? []
97  const changed = lines.filter(line => /^[12u?] /.test(line)).length
98  return { branch: head.slice('# branch.head '.length).trim(), changed, ahead: Number(ahead), behind: Number(behind) }
99}
100
101/** Reads `git rev-parse --show-toplevel`: the top folder of the worktree, the main checkout's or a linked one's. */
102export function parseWorktree(output: string): string | null {
103  const top = output.split(/\r?\n/)[0]?.trim() ?? ''
104  return top === '' ? null : top
105}
106
107function gitText(git: Git): string {
108  const marks = [git.changed > 0 ? `${git.changed} changed` : '', git.ahead > 0 ? `${git.ahead} ahead` : '', git.behind > 0 ? `${git.behind} behind` : '']
109  return [git.branch, ...marks.filter(mark => mark !== '')].join(' · ')
110}
111
112/**
113 * When a rate-limit window resets, in milliseconds since the epoch; NaN when the engine gave no time or one
114 * that cannot be read. A time without a zone is read as UTC, never as the machine's local time.
115 */
116export function resetTime(resetsAt: string | null): number {
117  if (resetsAt === null) return Number.NaN
118  return Date.parse(/(?:Z|[+-]\d{2}:?\d{2})$/i.test(resetsAt) ? resetsAt : `${resetsAt}Z`)
119}
120
121function limitText(percent: number, resetsAt: string | null, now: number): string {
122  const at = resetTime(resetsAt)
123  const left = Number.isFinite(at) && at > now ? ` · resets in ${coarse(at - now)}` : ''
124  return `${Math.round(percent)}%${left}`
125}
126
127/**
128 * The limits to warn about now: each at the red level, unless already warned about in its window. `warned`
129 * holds, by limit, the reset time of the window it was last warned in (null for a limit with none). A limit
130 * is warned about again only in a new window: a reset time other than the warned one, once the warned one
131 * has passed. A limit with no reset time is warned about once.
132 */
133export function limitsToWarn(limits: readonly Limit[], warned: Readonly<Record<string, string | null>>, now: number): Limit[] {
134  return limits.filter(limit => {
135    if (level(limit.percent, LIMIT_WARN_AT, LIMIT_DANGER_AT) !== 'danger') return false
136    if (!Object.hasOwn(warned, limit.kind)) return true
137    const last = warned[limit.kind] ?? null
138    const lastReset = resetTime(last)
139    return limit.resetsAt !== last && Number.isFinite(lastReset) && now >= lastReset
140  })
141}
142
143/** What the toast for a limit at the red level says: `5h limit at 91% · resets in 2h 5m`. */
144export function limitWarning(limit: Limit, now: number): string {
145  return `${LIMIT_NAMES[limit.kind] ?? limit.kind} at ${limitText(limit.percent, limit.resetsAt, now)}`
146}
147
148type Figure = { kind: SegmentId; id: string; label: string; text: string; level?: Level }
149
150/** What each figure is called, what it says and at what level, in the order drawn; the empty ones left out. */
151function figures(view: HudView, now: number): Figure[] {
152  const out: Figure[] = []
153  if (view.model !== '') out.push({ kind: 'model', id: 'model', label: 'model', text: shortModel(view.model) })
154  if (view.effort !== null) out.push({ kind: 'effort', id: 'effort', label: 'effort', text: view.effort })
155  if (view.contextPercent !== null) {
156    const percent = Math.round(view.contextPercent)
157    out.push({ kind: 'context', id: 'context', label: 'context', text: `${gauge(percent)} ${percent}%`, level: level(percent, 70, 85) })
158  }
159  for (const limit of view.limits) {
160    out.push({
161      kind: 'limits',
162      id: `limit-${limit.kind}`,
163      label: LIMIT_NAMES[limit.kind] ?? limit.kind,
164      text: limitText(limit.percent, limit.resetsAt, now),
165      level: level(limit.percent, LIMIT_WARN_AT, LIMIT_DANGER_AT),
166    })
167  }
168  if (view.isWorking) out.push({ kind: 'turn', id: 'turn', label: 'turn', text: duration(now - view.turnStartedAt) })
169  if (view.toolsSession > 0) out.push({ kind: 'tools', id: 'tools', label: 'tools', text: `${view.toolsTurn} this turn · ${view.toolsSession} total` })
170  if (view.agents > 0) out.push({ kind: 'agents', id: 'agents', label: 'agents', text: `${view.agents} running` })
171  if (view.git !== null) out.push({ kind: 'git', id: 'git', label: 'git', text: gitText(view.git) })
172  if (view.worktree !== null) out.push({ kind: 'worktree', id: 'worktree', label: WORKTREE_LABEL, text: folderName(view.worktree) })
173  if (view.costUsd !== null) out.push({ kind: 'cost', id: 'cost', label: 'cost', text: `$${view.costUsd.toFixed(2)}` })
174  if (view.startedAt > 0) out.push({ kind: 'session', id: 'session', label: 'session', text: coarse(now - view.startedAt) })
175  if (view.folder !== '') out.push({ kind: 'folder', id: 'folder', label: 'folder', text: folderName(view.folder) })
176  return out
177}
178
179/** Cells a text takes on a terminal: an emoji from the pictograph planes two, a variation selector none, the rest one. */
180export function cells(text: string): number {
181  return Array.from(text).reduce((sum, char) => {
182    const code = char.codePointAt(0) ?? 0
183    return sum + (code === 0xfe0f ? 0 : code >= 0x1f000 ? 2 : 1)
184  }, 0)
185}
186
187/** A line's width as drawn: each figure's label, a space and its text, with the gap between figures. */
188export function rowWidth(segments: readonly { label: string; text: string }[]): number {
189  return segments.reduce((sum, segment) => sum + cells(segment.label) + 1 + cells(segment.text), 0) + GAP * Math.max(0, segments.length - 1)
190}
191
192/**
193 * The row as drawn at `frame`, in its lines: the figures that are not hidden, each line cut to fit `columns`.
194 * A figure with a level takes that level's colour; the rest take the theme's, which move along the row while a turn runs.
195 */
196export function rows(view: HudView, config: Config, now: number, frame: number, columns: number): Segment[][] {
197  const shown = figures(view, now).filter(figure => !config.hidden.has(figure.kind))
198  const lines = [shown.filter(figure => FIRST_LINE.has(figure.kind)), shown.filter(figure => !FIRST_LINE.has(figure.kind))].map(line => {
199    let kept = line
200    for (const kind of DROP_ORDER) {
201      if (rowWidth(kept) <= columns) break
202      kept = kept.filter(figure => figure.kind !== kind)
203    }
204    return kept
205  })
206  const count = lines.reduce((sum, line) => sum + line.length, 0)
207  const palette = PALETTES[config.theme]
208  const isMoving = config.animate && view.isWorking
209  const shift = isMoving ? Math.floor(frame / 2) : 0
210  let index = 0
211  return lines
212    .filter(line => line.length > 0)
213    .map(line =>
214      line.map(figure => {
215        const at = index
216        index += 1
217        const isLit = isMoving && (at + shift) % Math.max(3, count) === 0
218        const themed = palette.length === 0 ? undefined : palette[(at + shift) % palette.length]
219        const isAlarm = figure.level === 'danger'
220        return {
221          id: figure.id,
222          kind: figure.kind,
223          label: figure.label,
224          text: figure.text,
225          color: figure.level === undefined ? themed : LEVEL_COLORS[figure.level],
226          isBold: isAlarm || isLit,
227          isInverse: isAlarm && isMoving && frame % 4 < 2,
228        }
229      }),
230    )
231}
232

1/** One rate-limit window as the engine reports it. */
2export type Limit = { kind: string; percent: number; resetsAt: string | null }
3
4/** The working tree's state, from one `git status`. */
5export type Git = { branch: string; changed: number; ahead: number; behind: number }
6
7/** The figures the row shows, as last read. */
8export type HudView = {
9  model: string
10  /** How hard the last request asked the model to think; null until a request has gone out, or for a model that takes none. */
11  effort: string | null
12  /** The context window's fill, 0-100; null until the engine has a reading. */
13  contextPercent: number | null
14  limits: Limit[]
15  costUsd: number | null
16  /** When the session began; 0 until first read. */
17  startedAt: number
18  /** Null outside a git repository. */
19  git: Git | null
20  /** The top folder of the worktree the session is in, the main checkout's or a linked one's; null outside a git repository. */
21  worktree: string | null
22  folder: string
23  /** Subagents running now. */
24  agents: number
25  toolsTurn: number
26  toolsSession: number
27  isWorking: boolean
28  turnStartedAt: number
29}
30
31declare module 'claude-code' {
32  interface PluginState {
33    /** `warned`: by limit, the reset time of the window its red level was last toasted in (null when it had none). */
34    hud: { view: HudView; frame: number; warned: Record<string, string | null> }
35  }
36}
37