context-meter

1import type { Register, SessionMeasureInput } from 'claude-code'
2
3type Reading = Pick<SessionMeasureInput, 'context' | 'rateLimits' | 'cost'>
4type Source = 'plan' | 'gateway' | 'api' | 'bedrock' | 'vertex' | 'foundry'
5
6// A Claude plan meters usage in a rolling 5-hour window and a weekly one; a gateway may set a spend
7// limit. Neither comes back on the API or a cloud provider, which bill per token instead.
8const LIMIT_NAMES: Record<string, string> = { five_hour: '5h limit', seven_day: 'weekly', seven_day_opus: 'weekly (Opus)', spend_limit: 'spend limit' }
9const SHORT_NAMES: Record<string, string> = { five_hour: '5h', seven_day: 'week', seven_day_opus: 'week (Opus)', spend_limit: 'spend' }
10const SOURCE_NAMES: Record<Source, string> = { plan: 'Claude plan', gateway: 'gateway', api: 'API', bedrock: 'Bedrock', vertex: 'Vertex AI', foundry: 'Foundry' }
11
12
13// "1h52m", "38m", "3d4h": how long until a window resets.
14export function resetIn(resetsAt: string | undefined, now: number): string | undefined {
15  if (!resetsAt) return undefined
16  const ms = Date.parse(resetsAt) - now
17  if (!(ms > 0)) return undefined
18  const m = Math.round(ms / 60_000)
19  if (m < 60) return `${m}m`
20  if (m < 24 * 60) return `${Math.floor(m / 60)}h${String(m % 60).padStart(2, '0')}m`
21  const h = Math.round(m / 60)
22  return `${Math.floor(h / 24)}d${h % 24 ? `${h % 24}h` : ''}`
23}
24
25export function sourceOf({ context, rateLimits }: Reading, provider: Source): Source | undefined {
26  if (rateLimits.some(r => r.kind === 'five_hour' || r.kind.startsWith('seven_day'))) return 'plan'
27  if (rateLimits.some(r => r.kind === 'spend_limit')) return 'gateway'
28  return context.percent !== undefined ? provider : undefined
29}
30
31// "ctx 62% · 5h 85% resets 1h52m · week 40%": plain words and numbers, which read the same in any
32// font (block gauges don't line up in the desktop's). A window's reset shows once it's past 70%.
33// On a plan the $ is only an API-rate estimate, so it's left out; elsewhere it's the bill.
34export function formatMeter({ context, rateLimits, cost }: Reading, source: Source | undefined, now: number): string {
35  const parts: string[] = []
36  if (context.percent !== undefined) parts.push(`ctx ${context.percent}%`)
37  for (const limit of rateLimits) {
38    const reset = limit.percentUsed >= 70 ? resetIn(limit.resetsAt, now) : undefined
39    parts.push(`${SHORT_NAMES[limit.kind] ?? limit.kind} ${Math.round(limit.percentUsed)}%${reset ? ` resets ${reset}` : ''}`)
40  }
41  if (cost && source && source !== 'plan') parts.push(`$${cost.usd.toFixed(2)} billed (${SOURCE_NAMES[source]})`)
42  else if (cost && !source) parts.push(`$${cost.usd.toFixed(2)}`)
43  return parts.join(' · ')
44}
45
46// Warns once per crossing; a reading back under the threshold (after /compact, a window reset) re-arms it.
47export function warnings(
48  { context, rateLimits }: Reading,
49  thresholds: { context: number; rateLimit: number },
50  warned: Set<string>,
51  now = Date.now(),
52): string[] {
53  const out: string[] = []
54  const check = (key: string, value: number, limit: number, message: string) => {
55    if (value < limit) warned.delete(key)
56    else if (!warned.has(key)) {
57      warned.add(key)
58      out.push(message)
59    }
60  }
61  if (context.percent !== undefined) {
62    check('ctx', context.percent, thresholds.context, `Context is ${context.percent}% full. Consider /compact or a fresh session.`)
63  }
64  for (const limit of rateLimits) {
65    const reset = resetIn(limit.resetsAt, now)
66    const name = LIMIT_NAMES[limit.kind] ?? limit.kind
67    check(`rl:${limit.kind}`, limit.percentUsed, thresholds.rateLimit, `Your Claude plan's ${name} is at ${Math.round(limit.percentUsed)}%${reset ? `; it resets in ${reset}` : ''}.`)
68  }
69  return out
70}
71
72export const register: Register = (on, options) => {
73  const thresholds = {
74    context: Number(options.contextWarnPercent ?? 80),
75    rateLimit: Number(options.rateLimitWarnPercent ?? 90),
76  }
77  const warned = new Set<string>()
78  let provider: Source = 'api'
79  let source: Source | undefined
80
81  on('session.start', async ($, e, next) => {
82    const started = await next(e)
83    // Which provider bills the tokens, from the switches Claude Code reads (never a key).
84    if (await $.env.get('CLAUDE_CODE_USE_BEDROCK').catch(() => undefined)) provider = 'bedrock'
85    else if (await $.env.get('CLAUDE_CODE_USE_VERTEX').catch(() => undefined)) provider = 'vertex'
86    else if (await $.env.get('CLAUDE_CODE_USE_FOUNDRY').catch(() => undefined)) provider = 'foundry'
87    const reading = await $.session.usage()
88    const now = await $.clock.now()
89    source = sourceOf(reading, provider) ?? source
90    $.ui.status(formatMeter(reading, source, now) || undefined)
91    for (const message of warnings(reading, thresholds, warned, now)) $.ui.toast(message)
92    return started
93  })
94
95  on('session.measure', async ($, e, next) => {
96    const measured = await next(e)
97    const now = await $.clock.now()
98    source = sourceOf(e, provider) ?? source
99    $.ui.status(formatMeter(e, source, now) || undefined)
100    for (const message of warnings(e, thresholds, warned, now)) $.ui.toast(message)
101    return measured
102  })
103}
104