usage-band

1import { atom, read, update } from 'claude-code'
2import type { Engine, Register, SessionContextUsage, SessionCost, SessionRateLimit } from 'claude-code'
3
4import type { Usage, UsageWindow } from '../types'
5
6const usage = atom({ plugin: 'usage-band', key: 'usage' } as const, { windows: [] } as Usage)
7const isHidden = atom({ plugin: 'usage-band', key: 'isHidden' } as const, false)
8// An atom, not a local, so setting it re-renders the band as soon as the mode is known.
9const chip = atom({ plugin: 'usage-band', key: 'chip' } as const, 'tack · …')
10
11const LABELS: Record<string, string> = { five_hour: '5h', seven_day: '7d', spend_limit: 'spend' }
12const WARN_AT = [80, 90]
13const BAR_CELLS = 10
14
15export function toUsage(context: SessionContextUsage, rateLimits: SessionRateLimit[], cost?: SessionCost): Usage {
16  return {
17    windows: rateLimits.map(({ kind, percentUsed, resetsAt }) => ({ kind, percentUsed, resetsAt })),
18    contextPercent: context.percent,
19    costUsd: cost?.usd,
20  }
21}
22
23export function bar(percent: number): string {
24  const filled = Math.min(BAR_CELLS, Math.max(0, Math.round((percent / 100) * BAR_CELLS)))
25  return '█'.repeat(filled) + '░'.repeat(BAR_CELLS - filled)
26}
27
28export function colorFor(percent: number): string {
29  if (percent >= 90) return 'red'
30  if (percent >= 70) return 'yellow'
31  return 'green'
32}
33
34// Same-day resets show only the time; later ones add the weekday, which is what the weekly window needs.
35export function resetLabel(resetsAt: string | undefined, now: number): string {
36  if (!resetsAt) return ''
37  const at = new Date(resetsAt)
38  if (Number.isNaN(at.getTime())) return ''
39  const time = `${String(at.getHours()).padStart(2, '0')}:${String(at.getMinutes()).padStart(2, '0')}`
40  const sameDay = new Date(now).toDateString() === at.toDateString()
41  if (sameDay) return `resets ${time}`
42  const day = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'][at.getDay()]
43  return `resets ${day} ${time}`
44}
45
46export function crossedWarning(before: UsageWindow[], after: UsageWindow[]): string | undefined {
47  for (const window of after) {
48    const previous = before.find(one => one.kind === window.kind)?.percentUsed ?? 0
49    const threshold = WARN_AT.filter(at => previous < at && window.percentUsed >= at).pop()
50    if (threshold !== undefined) {
51      return `${LABELS[window.kind] ?? window.kind} usage passed ${threshold}%`
52    }
53  }
54  return undefined
55}
56
57// A cost limit applies only in a project-only mode (tack prints a WARNING line for those)
58// and only when `tack config unleash-max-cost` holds a positive amount.
59export function costLimit(modeShow: string, configValue: string): number | undefined {
60  if (!modeShow.startsWith('WARNING:')) return undefined
61  const amount = Number(configValue.trim().split(' ')[0])
62  return Number.isFinite(amount) && amount > 0 ? amount : undefined
63}
64
65const CHIP_PENDING = 'tack · …'
66const CHIP_UNKNOWN = 'tack · ?'
67const CHIP_TRIES = 3
68
69// `tack mode` prints "<mode> (<source>)". `tack status --quiet` exits 1 when the project is not
70// enabled; any other failure (tack not found, an error) means the state is unknown, not off.
71export function modeChip(statusExit: number, modeOutput: string): string {
72  if (statusExit === 1) return 'tack · off'
73  const mode = modeOutput.trim().split(' ')[0]
74  return statusExit === 0 && mode ? `tack · ${mode}` : CHIP_UNKNOWN
75}
76
77export function chipNeedsRetry(label: string): boolean {
78  return label === CHIP_PENDING || label === CHIP_UNKNOWN
79}
80
81export function overBudget(costUsd: number | undefined, limitUsd: number | undefined): boolean {
82  return limitUsd !== undefined && costUsd !== undefined && costUsd >= limitUsd
83}
84
85export const register: Register = on => {
86  let limitUsd: number | undefined
87  let chipTries = 0
88  let chipError = ''
89
90  // Asks tack for the project's state; at session start the call can fail before the session is
91  // ready, so an unknown answer is retried with the next measurement instead of reading as off.
92  const refreshChip = async ($: Engine) => {
93    chipTries += 1
94    try {
95      const status = await $.process.run(['tack', 'status', '--quiet'], { timeoutMs: 5000 })
96      const mode = await $.process.run(['tack', 'mode'], { timeoutMs: 5000 })
97      const label = modeChip(status.exitCode, mode.exitCode === 0 ? mode.stdout : '')
98      chipError = label === CHIP_UNKNOWN ? `tack status exited ${status.exitCode}: ${status.stderr.trim()}` : ''
99      await update($, chip, () => label)
100    } catch (error) {
101      chipError = `could not run tack: ${error instanceof Error ? error.message : String(error)}`
102      await update($, chip, () => CHIP_UNKNOWN)
103    }
104  }
105
106  on('session.start', async ($, e, next) => {
107    const { context, rateLimits, cost } = await $.session.usage()
108    await update($, usage, () => toUsage(context, rateLimits, cost))
109    await $.command.register({ name: 'usage-band', description: 'Show or hide the usage band above the prompt' })
110    try {
111      const mode = await $.process.run(['tack', 'mode', 'show'], { timeoutMs: 5000 })
112      const config = await $.process.run(['tack', 'config', 'unleash-max-cost', '--get'], { timeoutMs: 5000 })
113      limitUsd = mode.exitCode === 0 && config.exitCode === 0 ? costLimit(mode.stdout, config.stdout) : undefined
114    } catch {
115      limitUsd = undefined
116    }
117    await refreshChip($)
118    return next(e)
119  })
120
121  on('tool.call', async ($, e, next) => {
122    const current = await read($, usage)
123    if (overBudget(current.costUsd, limitUsd)) {
124      return {
125        deny: `This autonomous session reached its cost limit of $${limitUsd} (tack config unleash-max-cost). Stop, update the handoff and summarise what is done, what is pending and the assumptions made.`,
126      }
127    }
128    return next(e)
129  })
130
131  on('session.measure', async ($, e, next) => {
132    const before = (await read($, usage)).windows
133    const after = toUsage(e.context, e.rateLimits, e.cost)
134    await update($, usage, () => after)
135    const warning = crossedWarning(before, after.windows)
136    if (warning) $.ui.toast(warning)
137    if (chipTries < CHIP_TRIES && chipNeedsRetry(await read($, chip))) await refreshChip($)
138    return next(e)
139  })
140
141  on('command.run', { command: 'usage-band' }, async $ => {
142    const hidden = await update($, isHidden, value => !value)
143    const why = chipError ? ` (tack chip: ${chipError})` : ''
144    return { text: (hidden ? 'Usage band hidden.' : 'Usage band shown.') + why }
145  })
146
147  on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
148    const current = await read($, usage)
149    if (e.props.hasSurvey || (await read($, isHidden))) return next(e)
150
151    const { Box, Text } = $.ui.resolve(e)
152    const now = await $.clock.now()
153    const hasData = current.windows.length > 0 || current.contextPercent !== undefined
154
155    return (
156      <Box flexDirection="row" gap={3}>
157        <Text color="cyan">{await read($, chip)}</Text>
158        {!hasData && <Text dimColor>usage: waiting for the first response</Text>}
159        {current.windows.map(window => (
160          <Box key={window.kind} flexDirection="row" gap={1}>
161            <Text bold>{LABELS[window.kind] ?? window.kind}</Text>
162            <Text color={colorFor(window.percentUsed)}>{bar(window.percentUsed)}</Text>
163            <Text>{`${Math.round(window.percentUsed)}%`}</Text>
164            <Text dimColor>{resetLabel(window.resetsAt, now)}</Text>
165          </Box>
166        ))}
167        {current.contextPercent !== undefined && (
168          <Text dimColor>{`ctx ${current.contextPercent}%`}</Text>
169        )}
170        {current.costUsd !== undefined && <Text dimColor>{`$${current.costUsd.toFixed(2)}`}</Text>}
171      </Box>
172    )
173  })
174}
175

1export type UsageWindow = { kind: string; percentUsed: number; resetsAt?: string }
2
3export type Usage = {
4  windows: UsageWindow[]
5  contextPercent?: number
6  costUsd?: number
7}
8
9declare module 'claude-code' {
10  interface PluginState {
11    'usage-band': { usage: Usage; isHidden: boolean; chip: string }
12  }
13}
14