usage-gauge

1import { atom, read, update } from 'claude-code'
2import type { EngineInterface, Register } from 'claude-code'
3
4import { kb, nameOf, resetLabel } from './format'
5
6const REFRESH_MS = 20_000
7
8const snap = atom({ plugin: 'usage-gauge', key: 'snap' } as const, null)
9
10// The engine's own figures (the ones its status line shows). Free: no model call.
11async function refresh($: EngineInterface) {
12  const usage = await $.session.usage()
13  const at = await $.clock.now()
14  await update($, snap, () => ({
15    contextTokens: usage.context.tokens ?? null,
16    contextWindow: usage.context.window,
17    contextPercent: usage.context.percent ?? null,
18    limits: usage.rateLimits.map(one => ({
19      kind: one.kind,
20      percentUsed: one.percentUsed,
21      resetsAt: one.resetsAt,
22    })),
23    usd: usage.cost?.usd ?? null,
24    at,
25  }))
26}
27
28export const register: Register = on => {
29  on('session.start', async ($, e, next) => {
30    await $.command.register({
31      name: 'gauge',
32      description: '额度看板：对话上下文、5 小时额度、本周额度、花费',
33    })
34    void refresh($).catch(() => undefined)
35    $.clock.every(REFRESH_MS, () => void refresh($).catch(() => undefined))
36
37    return next(e)
38  })
39
40  on('turn.complete', async ($, e, next) => {
41    if (e.agentId === undefined) void refresh($).catch(() => undefined)
42
43    return next(e)
44  }).catch(($, e, next) => next(e))
45
46  on('command.run', { command: 'gauge' }, async $ => {
47    await refresh($)
48    const s = await read($, snap)
49    if (s === null) return { text: '还没读到额度。' }
50    const now = await $.clock.now()
51    const lines = [
52      `对话上下文：${s.contextPercent ?? '?'}%（${s.contextTokens === null ? '?' : kb(s.contextTokens)} / ${kb(s.contextWindow)}）`,
53      ...s.limits.map(one => `${nameOf(one.kind)}额度：已用 ${one.percentUsed}% ${resetLabel(one.resetsAt, now)}`),
54      s.limits.length === 0 ? '额度：引擎还没读到（发一条消息后出现）' : '',
55      s.usd === null ? '' : `本次对话花费：$${s.usd.toFixed(2)}`,
56    ]
57
58    return { text: lines.filter(line => line !== '').join('\n') }
59  })
60}
61

1// Pure: how a number becomes a bar, a color and a reset time.
2
3const WIDTH = 8
4const DAYS = ['周日', '周一', '周二', '周三', '周四', '周五', '周六']
5
6export const bar = (percent: number) => {
7  const on = Math.max(0, Math.min(WIDTH, Math.round((percent / 100) * WIDTH)))
8
9  return { on: '▓'.repeat(on), off: '░'.repeat(WIDTH - on) }
10}
11
12export const colorOf = (percent: number) =>
13  percent >= 85 ? 'red' : percent >= 60 ? 'yellow' : 'green'
14
15export const kb = (tokens: number) =>
16  tokens >= 1_000_000 ? `${(tokens / 1_000_000).toFixed(1)}M` : `${Math.round(tokens / 1000)}k`
17
18const two = (n: number) => String(n).padStart(2, '0')
19
20// "15:00" when the reset is today, "周六 17:00" otherwise.
21export const resetLabel = (iso: string | undefined, nowMs: number): string => {
22  if (iso === undefined) return ''
23  const at = new Date(iso)
24  if (Number.isNaN(at.getTime())) return ''
25  const today = new Date(nowMs)
26  const isToday =
27    at.getFullYear() === today.getFullYear() &&
28    at.getMonth() === today.getMonth() &&
29    at.getDate() === today.getDate()
30  const time = `${two(at.getHours())}:${two(at.getMinutes())}`
31
32  return isToday ? `↻ ${time}` : `↻ ${DAYS[at.getDay()]} ${time}`
33}
34
35export const nameOf = (kind: string) =>
36  kind === 'five_hour' ? '5 小时' : kind === 'seven_day' ? '本周' : kind === 'spend_limit' ? '预算' : kind
37

1export type GaugeLimit = { kind: string; percentUsed: number; resetsAt?: string }
2
3export type GaugeSnap = {
4  contextTokens: number | null
5  contextWindow: number
6  contextPercent: number | null
7  limits: GaugeLimit[]
8  usd: number | null
9  at: number
10}
11
12declare module 'claude-code' {
13  interface PluginState {
14    'usage-gauge': { snap: GaugeSnap | null }
15    // Read-only view of Switchboard's value (it alone writes it).
16    switchboard: { flags: Record<string, { isOn: boolean; isHidden: boolean }> }
17  }
18}
19