usage-pacer

1import { atom, read, update } from 'claude-code'
2import type { EngineInterface, Register, SessionRateLimit } from 'claude-code'
3
4import type { SessionActivity, UsageWarnings } from '../types'
5
6const LEVELS = [95, 80]
7const LABELS: Record<string, string> = { five_hour: '5h', seven_day: '7d', spend_limit: 'spend' }
8const REFRESH_MS = 60_000
9const HANDOFF_TURNS = 5
10const HANDOFF_RECENT_MS = 20 * 60_000
11
12const warned = atom({ plugin: 'usage-pacer', key: 'warned' } as const, {} as UsageWarnings)
13const activity = atom({ plugin: 'usage-pacer', key: 'activity' } as const, { turns: 0, lastAt: 0, isInteractive: false } as SessionActivity)
14const handedOff = atom({ plugin: 'usage-pacer', key: 'handedOff' } as const, '')
15
16const label = (kind: string) => LABELS[kind] ?? kind.replaceAll('_', ' ')
17
18const percent = (limit: SessionRateLimit) => Math.round(limit.percentUsed)
19
20const timeLeft = (resetsAt: string | undefined, now: number) => {
21  if (resetsAt === undefined) return undefined
22  const minutes = Math.ceil((Date.parse(resetsAt) - now) / 60_000)
23  if (!(minutes > 0)) return undefined
24  if (minutes < 60) return `${minutes}m`
25  const hours = Math.floor(minutes / 60)
26  if (hours < 24) return `${hours}h${String(minutes % 60).padStart(2, '0')}m`
27  return `${Math.floor(hours / 24)}d${hours % 24}h`
28}
29
30const statusText = (limits: readonly SessionRateLimit[], now: number) =>
31  limits
32    .map(limit => {
33      const left = timeLeft(limit.resetsAt, now)
34      return `${label(limit.kind)} ${percent(limit)}%${left ? ` (resets in ${left})` : ''}`
35    })
36    .join(' · ')
37
38const warningText = (limit: SessionRateLimit, level: number, now: number) => {
39  const head = `${label(limit.kind)} usage ${percent(limit)}%`
40  if (level < 95) return `${head} — consider /model sonnet for bulk work or scans`
41  const left = timeLeft(limit.resetsAt, now)
42  return `${head} — almost at the limit${left ? `, resets in ${left}` : ''}`
43}
44
45const isActive = (seen: SessionActivity, now: number) =>
46  seen.isInteractive && seen.turns >= HANDOFF_TURNS && now - seen.lastAt <= HANDOFF_RECENT_MS
47
48const startHandoff = ($: EngineInterface) => {
49  $.clock.after(0, () => {
50    void $.command.run({ command: 'handoff', args: '' }).catch(() => $.ui.toast('usage-pacer: /handoff did not start, run it yourself'))
51  })
52}
53
54const pace = async ($: EngineInterface, limits: readonly SessionRateLimit[], handoffAt: number) => {
55  const now = await $.clock.now()
56  $.ui.status(limits.length === 0 ? undefined : statusText(limits, now))
57
58  const before = await read($, warned)
59  const toasts: { kind: string; text: string }[] = []
60  const after: UsageWarnings = {}
61
62  for (const limit of limits) {
63    const resetsAt = limit.resetsAt ?? ''
64    const kept = before[limit.kind]
65    const levels = kept !== undefined && kept.resetsAt === resetsAt ? kept.levels : []
66    const reached = LEVELS.find(level => limit.percentUsed >= level)
67    if (reached !== undefined && !levels.includes(reached)) toasts.push({ kind: limit.kind, text: warningText(limit, reached, now) })
68    after[limit.kind] = {
69      resetsAt,
70      levels: reached === undefined ? levels : [...new Set([...levels, ...LEVELS.filter(level => level <= reached)])],
71    }
72  }
73
74  await update($, warned, () => after)
75
76  const five = limits.find(limit => limit.kind === 'five_hour')
77  if (handoffAt > 0 && five !== undefined && five.percentUsed >= handoffAt) {
78    const window = five.resetsAt ?? 'unknown'
79    if ((await read($, handedOff)) !== window && isActive(await read($, activity), now)) {
80      await update($, handedOff, () => window)
81      const text = `5h usage ${percent(five)}% — writing a handoff now so you can switch accounts`
82      const at = toasts.findIndex(toast => toast.kind === 'five_hour')
83      if (at >= 0) toasts[at] = { kind: 'five_hour', text }
84      else toasts.push({ kind: 'five_hour', text })
85      startHandoff($)
86    }
87  }
88
89  for (const toast of toasts) $.ui.toast(toast.text, { timeoutMs: 10_000 })
90}
91
92export const register: Register = (on, options) => {
93  const above = Number(options.sonnetSubagentsAbove ?? 0)
94  const handoffAt = Number(options.handoffAt ?? 0)
95
96  on('session.start', async ($, e, next) => {
97    const started = await next(e)
98    await update($, activity, seen => ({ ...seen, isInteractive: e.isInteractive }))
99    $.clock.every(REFRESH_MS, () => {
100      void $.session.usage().then(usage => pace($, usage.rateLimits, handoffAt))
101    })
102    return started
103  })
104
105  on('turn.complete', async ($, e, next) => {
106    const done = await next(e)
107    if (e.agentId === undefined) {
108      const now = await $.clock.now()
109      await update($, activity, seen => ({ ...seen, turns: seen.turns + 1, lastAt: now }))
110    }
111    return done
112  })
113
114  on('session.measure', async ($, e, next) => {
115    if (e.changed.includes('rateLimits')) await pace($, e.rateLimits, handoffAt)
116    return next(e)
117  })
118
119  if (above > 0) {
120    on('agent.spawn', async ($, e, next) => {
121      const isPinned = e.fork || e.workflow !== undefined || e.isTeammate === true || e.model !== undefined
122      if (isPinned || e.subagentType !== 'general-purpose' || !/opus/i.test(e.parentModel)) return next(e)
123      const { rateLimits } = await $.session.usage()
124      const peak = Math.max(0, ...rateLimits.map(limit => limit.percentUsed))
125      if (peak <= above) return next(e)
126      $.ui.log(`usage-pacer: "${e.description}" runs on sonnet, usage at ${Math.round(peak)}%`)
127      return next({ ...e, model: 'sonnet' })
128    })
129  }
130}
131

1export type UsageWarning = { resetsAt: string; levels: number[] }
2
3export type UsageWarnings = Record<string, UsageWarning>
4
5export type SessionActivity = { turns: number; lastAt: number; isInteractive: boolean }
6
7declare module 'claude-code' {
8  interface PluginState {
9    'usage-pacer': { warned: UsageWarnings; activity: SessionActivity; handedOff: string }
10  }
11}
12