usage-meter

1import { atom, read, update } from 'claude-code'
2import type { EngineInterface, ModelUsage, Register, RenderSurface, SessionMeasureInput } from 'claude-code'
3
4import type { Limit, Reading, Snapshot, Task, TaskRecord } from '../types'
5
6const snapshotAtom = atom({ plugin: 'usage-meter', key: 'snapshot' } as const, null)
7const taskAtom = atom({ plugin: 'usage-meter', key: 'task' } as const, null)
8const historyAtom = atom({ plugin: 'usage-meter', key: 'history' } as const, [])
9const localAtom = atom({ plugin: 'usage-meter', key: 'local' } as const, null)
10const shownAtom = atom({ plugin: 'usage-meter', key: 'shown' } as const, null)
11
12const HISTORY_SIZE = 20
13const STORE_KEY = 'limits'
14const TICK_MS = 60_000
15
16export const SHARING_NOTE =
17  'Plan limits update when any Claude Code window on this computer gets a model reply; usage from other computers shows up after your next message here.'
18
19let stopTick: (() => void) | null = null
20
21type Measured = Pick<SessionMeasureInput, 'context' | 'rateLimits' | 'cost'>
22
23const toSnapshot = (u: Measured): Snapshot => ({
24  contextTokens: u.context.tokens ?? null,
25  contextWindow: u.context.window,
26  contextPercent: u.context.percent ?? null,
27  limits: u.rateLimits.map(r => ({ kind: r.kind, percentUsed: r.percentUsed, resetsAt: r.resetsAt })),
28  usd: u.cost?.usd ?? null,
29})
30
31const limitsKey = (ls: Limit[]) =>
32  JSON.stringify([...ls].sort((a, b) => a.kind.localeCompare(b.kind)).map(l => [l.kind, l.percentUsed, l.resetsAt ?? null]))
33
34export const sameLimits = (a: Limit[], b: Limit[]) => limitsKey(a) === limitsKey(b)
35
36const isLimit = (v: unknown): v is Limit => {
37  if (typeof v !== 'object' || v === null) return false
38  const l = v as Record<string, unknown>
39  return typeof l.kind === 'string' && typeof l.percentUsed === 'number' && (l.resetsAt === undefined || typeof l.resetsAt === 'string')
40}
41
42export const parseReading = (v: unknown): Reading | null => {
43  if (typeof v !== 'object' || v === null) return null
44  const r = v as Record<string, unknown>
45  if (typeof r.at !== 'number' || typeof r.source !== 'string' || !Array.isArray(r.limits)) return null
46  const limits = r.limits.filter(isLimit)
47  if (limits.length === 0) return null
48  return { at: r.at, source: r.source, limits: limits.map(l => ({ kind: l.kind, percentUsed: l.percentUsed, resetsAt: l.resetsAt })) }
49}
50
51export const newest = (current: Reading | null, ...candidates: (Reading | null)[]) =>
52  candidates.reduce<Reading | null>((best, r) => (r && (!best || r.at > best.at) ? r : best), current)
53
54export const sourceOf = (surfaces: readonly RenderSurface[]) =>
55  surfaces[0] === 'terminal' ? 'CLI' : surfaces.includes('desktop') ? 'app' : (surfaces[0] ?? 'headless')
56
57const pad2 = (n: number) => `${n}`.padStart(2, '0')
58
59export const fmtClock = (ms: number) => {
60  const d = new Date(ms)
61  return `${pad2(d.getHours())}:${pad2(d.getMinutes())}:${pad2(d.getSeconds())}`
62}
63
64const asOf = (r: Reading) => `as of ${fmtClock(r.at)} (${r.source})`
65
66const viewOf = (snap: Snapshot, shown: Reading | null): Snapshot => (shown ? { ...snap, limits: shown.limits } : snap)
67
68const totalTokens = (u: ModelUsage) =>
69  u.input_tokens + u.output_tokens + u.cache_read_input_tokens + u.cache_creation_input_tokens
70
71const fiveHour = (s: Snapshot | null) => s?.limits.find(l => l.kind === 'five_hour')?.percentUsed ?? null
72
73export const fmtTokens = (n: number) => {
74  if (n < 1000) return `${Math.round(n)}`
75  if (n < 1_000_000) return `${(n / 1000).toFixed(n < 10_000 ? 1 : 0)}K`
76  return `${(n / 1_000_000).toFixed(2)}M`
77}
78
79const fmtUsd = (n: number) => `$${n < 1 ? n.toFixed(3) : n.toFixed(2)}`
80
81const fmtDuration = (ms: number) => {
82  const minutes = Math.max(0, Math.round(ms / 60_000))
83  const d = Math.floor(minutes / 1440)
84  const h = Math.floor((minutes % 1440) / 60)
85  const m = minutes % 60
86  if (d > 0) return `${d}d ${h}h`
87  if (h > 0) return `${h}h ${m}m`
88  return `${m}m`
89}
90
91const limitLabel = (kind: string) =>
92  ({ five_hour: '5h', seven_day: '7d', seven_day_opus: '7d Opus', seven_day_sonnet: '7d Sonnet', spend_limit: 'Spend' })[kind] ??
93  kind.replace(/_/g, ' ')
94
95const levelColor = (pct: number) => (pct >= 90 ? 'red' : pct >= 70 ? 'yellow' : 'green')
96
97export const bar = (pct: number, width: number) => {
98  const filled = Math.round((Math.min(100, Math.max(0, pct)) / 100) * width)
99  return { filled: '█'.repeat(filled), empty: '░'.repeat(width - filled) }
100}
101
102const barText = (pct: number, width: number) => {
103  const b = bar(pct, width)
104  return b.filled + b.empty
105}
106
107export type Estimate = { tasks: number; avgTokens: number; avgUsd: number | null; avgFiveHour: number | null }
108
109export const estimate = (history: TaskRecord[]): Estimate | null => {
110  const done = history.filter(h => h.tokens > 0)
111  if (done.length === 0) return null
112  const avg = (xs: number[]) => (xs.length ? xs.reduce((a, b) => a + b, 0) / xs.length : null)
113  return {
114    tasks: done.length,
115    avgTokens: avg(done.map(h => h.tokens)) ?? 0,
116    avgUsd: avg(done.flatMap(h => (h.usd === null ? [] : [h.usd]))),
117    avgFiveHour: avg(done.flatMap(h => (h.fiveHourDelta === null ? [] : [h.fiveHourDelta]))),
118  }
119}
120
121const limitLine = (l: Limit, now: number) => {
122  const left = Math.max(0, 100 - l.percentUsed)
123  const reset = l.resetsAt ? `, resets in ${fmtDuration(Date.parse(l.resetsAt) - now)}` : ''
124  return `${limitLabel(l.kind)} ${l.percentUsed}% used (${left.toFixed(0)}% left${reset})`
125}
126
127const tasksLeft = (snap: Snapshot | null, est: Estimate | null) => {
128  const used = fiveHour(snap)
129  if (used === null || !est?.avgFiveHour || est.avgFiveHour <= 0) return null
130  return Math.floor(Math.max(0, 100 - used) / est.avgFiveHour)
131}
132
133const taskLine = (task: Task | null, snap: Snapshot | null, est: Estimate | null) => {
134  if (!task) return 'Task: no task yet; estimates appear after the first one'
135  const liveUsd = task.isRunning
136    ? snap?.usd != null && task.startUsd != null
137      ? snap.usd - task.startUsd
138      : null
139    : task.usd
140  const parts = [
141    `${fmtTokens(task.tokens)} tok (out ${fmtTokens(task.output)}, ${task.requests} req)`,
142    ...(liveUsd != null ? [fmtUsd(liveUsd)] : []),
143  ]
144  if (task.isRunning) {
145    if (est) {
146      const projected = Math.max(task.tokens, est.avgTokens)
147      const usd = est.avgUsd != null ? ` / ${fmtUsd(Math.max(liveUsd ?? 0, est.avgUsd))}` : ''
148      parts.push(`est. total ~${fmtTokens(projected)}${usd} (avg of ${est.tasks})`)
149    }
150    return `Task running: ${parts.join(' · ')}`
151  }
152  if (task.fiveHourDelta != null) parts.push(`5h +${task.fiveHourDelta.toFixed(1)}%`)
153  const left = tasksLeft(snap, est)
154  if (left !== null) parts.push(`~${left} more such tasks fit in the 5h window`)
155  return `Last task: ${parts.join(' · ')}`
156}
157
158const sessionLine = (snap: Snapshot) => {
159  const ctx =
160    snap.contextTokens != null
161      ? `Context (this window) ${snap.contextPercent ?? 0}% (${fmtTokens(snap.contextTokens)} / ${fmtTokens(snap.contextWindow)})`
162      : `Context (this window): ${fmtTokens(snap.contextWindow)} window`
163  const cost = snap.usd != null ? `Session ${fmtUsd(snap.usd)}` : 'Session cost n/a'
164  return `${cost} · ${ctx}`
165}
166
167const sourceLabel = async ($: EngineInterface) => {
168  try {
169    return sourceOf(await $.session.surfaces())
170  } catch {
171    return sourceOf([])
172  }
173}
174
175const readStored = async ($: EngineInterface) => {
176  try {
177    return parseReading(await $.store.get(STORE_KEY))
178  } catch {
179    return null
180  }
181}
182
183const publish = async ($: EngineInterface, reading: Reading) => {
184  try {
185    const stored = await readStored($)
186    if (stored && stored.at >= reading.at) return
187    await $.store.set(STORE_KEY, reading)
188  } catch {}
189}
190
191const show = ($: EngineInterface, ...candidates: (Reading | null)[]) =>
192  update($, shownAtom, current => newest(current ?? null, ...candidates))
193
194const observe = async ($: EngineInterface, limits: Limit[], isFresh: boolean) => {
195  if (limits.length === 0) return
196  const prev = await read($, localAtom)
197  if (!isFresh && prev && sameLimits(prev.limits, limits)) return
198  const reading: Reading = { at: await $.clock.now(), limits, source: await sourceLabel($) }
199  await update($, localAtom, () => reading)
200  await publish($, reading)
201  await show($, reading)
202}
203
204const refresh = async ($: EngineInterface) => {
205  const snap = toSnapshot(await $.session.usage())
206  await update($, snapshotAtom, () => snap)
207  await observe($, snap.limits, false)
208  await show($, await readStored($))
209  return snap
210}
211
212export const register: Register = on => {
213  on('session.start', async ($, e, next) => {
214    await $.command.register({
215      name: 'usage-meter',
216      description: 'Plan usage, remaining limits, session cost and task token estimates',
217      immediate: true,
218    })
219    await refresh($)
220    stopTick?.()
221    const timer = $.clock.every(TICK_MS, () => {
222      refresh($).catch(() => {})
223    })
224    stopTick = () => timer.cancel()
225    return next(e)
226  })
227
228  on('session.measure', async ($, e, next) => {
229    const snap = toSnapshot(e)
230    await update($, snapshotAtom, () => snap)
231    await observe($, snap.limits, e.changed.includes('rateLimits') || e.changed.includes('context'))
232    return next(e)
233  })
234
235  on('turn.start', async ($, e, next) => {
236    const usage = await $.session.usage()
237    const snap = toSnapshot(usage)
238    await update($, snapshotAtom, () => snap)
239    const task: Task = {
240      startedAt: await $.clock.now(),
241      startUsd: snap.usd,
242      startFiveHour: fiveHour(snap),
243      tokens: 0,
244      output: 0,
245      requests: 0,
246      isRunning: true,
247      usd: null,
248      fiveHourDelta: null,
249      durationMs: 0,
250    }
251    await update($, taskAtom, () => task)
252    return next(e)
253  })
254
255  on('turn.step', async function* ($, e, next) {
256    const result = yield* next(e)
257    const usage = result.usage
258    if (usage) {
259      await update($, taskAtom, t =>
260        t?.isRunning
261          ? { ...t, tokens: t.tokens + totalTokens(usage), output: t.output + usage.output_tokens, requests: t.requests + 1 }
262          : t,
263      )
264    }
265    return result
266  })
267
268  on('turn.complete', async ($, e, next) => {
269    if (e.agentId) return next(e)
270    const snap = toSnapshot(await $.session.usage())
271    await update($, snapshotAtom, () => snap)
272    await observe($, snap.limits, false)
273    const now = await $.clock.now()
274    const finished = await update($, taskAtom, t => {
275      if (!t?.isRunning) return t
276      const tokens = t.tokens === 0 && e.usage ? totalTokens(e.usage) : t.tokens
277      const output = t.output === 0 && e.usage ? e.usage.output_tokens : t.output
278      const endFiveHour = fiveHour(snap)
279      const delta = endFiveHour !== null && t.startFiveHour !== null ? endFiveHour - t.startFiveHour : null
280      return {
281        ...t,
282        tokens,
283        output,
284        isRunning: false,
285        usd: snap.usd != null && t.startUsd != null ? snap.usd - t.startUsd : null,
286        fiveHourDelta: delta !== null && delta >= 0 ? delta : null,
287        durationMs: now - t.startedAt,
288      }
289    })
290    if (finished && !finished.isRunning && finished.tokens > 0 && !e.isAborted) {
291      const record: TaskRecord = { tokens: finished.tokens, usd: finished.usd, fiveHourDelta: finished.fiveHourDelta }
292      await update($, historyAtom, h => [...h, record].slice(-HISTORY_SIZE))
293    }
294    return next(e)
295  })
296
297  on('command.run', { command: 'usage-meter' }, async $ => {
298    const snap = await refresh($)
299    const shown = await read($, shownAtom)
300    const view = viewOf(snap, shown)
301    const task = await read($, taskAtom)
302    const history = await read($, historyAtom)
303    const est = estimate(history)
304    const now = await $.clock.now()
305    const age = shown ? (now - shown.at < 60_000 ? 'just now' : `${fmtDuration(now - shown.at)} ago`) : ''
306    const lines = [shown ? `Plan usage · ${asOf(shown)}, ${age}` : 'Plan usage']
307    if (view.limits.length === 0) {
308      lines.push('  No plan rate limits reported (API-key billing, or no response yet).')
309      lines.push('  A prepaid credit balance is not exposed to Claude Code; check the Console billing page.')
310    } else {
311      for (const l of view.limits) lines.push(`  ${barText(l.percentUsed, 20)} ${limitLine(l, now)}`)
312    }
313    lines.push('', sessionLine(snap), taskLine(task, view, est))
314    if (est) {
315      const usd = est.avgUsd != null ? `, ${fmtUsd(est.avgUsd)}` : ''
316      const pct = est.avgFiveHour != null ? `, ${est.avgFiveHour.toFixed(1)}% of 5h window` : ''
317      lines.push(`Average task (last ${est.tasks}): ~${fmtTokens(est.avgTokens)} tok${usd}${pct}`)
318    }
319    lines.push('', SHARING_NOTE)
320    return { text: lines.join('\n') }
321  })
322
323  on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
324    const snap = await read($, snapshotAtom)
325    if (e.props.hasSurvey || !snap) return next(e)
326
327    const shown = await read($, shownAtom)
328    const view = viewOf(snap, shown)
329    const task = await read($, taskAtom)
330    const est = estimate(await read($, historyAtom))
331    const { Box, Text } = $.ui.resolve(e)
332    const now = await $.clock.now()
333
334    const width = Math.min(30, Math.max(10, e.props.bodyColumns - 50))
335
336    const meter = (key: string, label: string, pct: number, color: string, detail: string) => {
337      const b = bar(pct, width)
338      return (
339        <Box key={key}>
340          <Text dimColor>{label.padEnd(9)}</Text>
341          <Text color={color}>{b.filled}</Text>
342          <Text dimColor>{b.empty}</Text>
343          <Text color={color} bold>
344            {` ${Math.round(pct)}%`.padStart(5)}
345          </Text>
346          <Text dimColor> {detail}</Text>
347        </Box>
348      )
349    }
350
351    const rows = view.limits.length
352      ? view.limits.map((l, i) => {
353          const left = Math.max(0, 100 - l.percentUsed).toFixed(0)
354          const reset = l.resetsAt ? ` · resets in ${fmtDuration(Date.parse(l.resetsAt) - now)}` : ''
355          const note = i === 0 && shown ? ` · ${asOf(shown)}` : ''
356          return meter(`limit-${l.kind}`, limitLabel(l.kind), l.percentUsed, levelColor(l.percentUsed), `${left}% left${reset}${note}`)
357        })
358      : [
359          <Box key="plan">
360            <Text dimColor>{'Plan'.padEnd(9)}no rate limits reported (API billing; credit balance not exposed)</Text>
361          </Box>,
362        ]
363
364    if (snap.contextTokens != null) {
365      const pct = snap.contextPercent ?? 0
366      rows.push(meter('context', 'Context', pct, levelColor(pct), `${fmtTokens(snap.contextTokens)} / ${fmtTokens(snap.contextWindow)} · this window`))
367    }
368
369    const cost = snap.usd != null ? `Session ${fmtUsd(snap.usd)}` : 'Session cost n/a'
370    if (task?.isRunning && est) {
371      const ratio = (task.tokens / est.avgTokens) * 100
372      const color = ratio > 100 ? 'red' : ratio >= 80 ? 'yellow' : 'cyan'
373      rows.push(meter('task', 'Task', ratio, color, `${fmtTokens(task.tokens)} / ~${fmtTokens(est.avgTokens)} tok est. (avg of ${est.tasks})`))
374      rows.push(
375        <Box key="footer">
376          <Text dimColor>{cost}</Text>
377        </Box>,
378      )
379    } else {
380      rows.push(
381        <Box key="footer">
382          <Text dimColor={!task?.isRunning} color={task?.isRunning ? 'cyan' : undefined}>
383            {`${cost} · ${taskLine(task, view, est)}`}
384          </Text>
385        </Box>,
386      )
387    }
388
389    return <Box flexDirection="column">{rows.slice(0, Math.max(1, e.props.maxRows))}</Box>
390  })
391}
392

1export type Limit = { kind: string; percentUsed: number; resetsAt?: string }
2
3export type Snapshot = {
4  contextTokens: number | null
5  contextWindow: number
6  contextPercent: number | null
7  limits: Limit[]
8  usd: number | null
9}
10
11export type Task = {
12  startedAt: number
13  startUsd: number | null
14  startFiveHour: number | null
15  tokens: number
16  output: number
17  requests: number
18  isRunning: boolean
19  usd: number | null
20  fiveHourDelta: number | null
21  durationMs: number
22}
23
24export type Reading = { at: number; limits: Limit[]; source: string }
25
26export type TaskRecord = { tokens: number; usd: number | null; fiveHourDelta: number | null }
27
28declare module 'claude-code' {
29  interface PluginState {
30    'usage-meter': {
31      snapshot: Snapshot | null
32      task: Task | null
33      history: TaskRecord[]
34      local: Reading | null
35      shown: Reading | null
36    }
37  }
38}
39