agent-spend

1import { atom, read, update } from 'claude-code'
2import type { EngineInterface, On, Register } from 'claude-code'
3
4import type { Spend } from '../types'
5import { costliest, groups, parse, summary } from './spend.ts'
6import type { Group } from './spend.ts'
7
8const PANE = 'agent-spend'
9const spend = atom({ plugin: 'agent-spend', key: 'spend' } as const, null)
10
11// <metrics: generated from shared/metrics.ts by shared/sync.sh>
12// Shared mod metrics (schema v2). Source of truth: ~/.claude/mods/shared/metrics.ts.
13// shared/sync.sh inlines it between the metrics markers in each mod's register.tsx (the engine only lets $
14// into functions declared in the same file). Edit here, run sync.sh, never edit an inlined copy.
15//
16// Rows appended to ~/.claude/mods/metrics.jsonl, all with { v: 2, t, mod, event, ver, session, project }:
17//   loaded   once per load (logLoaded, or count() in the mod's session.start hook), at session.start: proves which version of the mod is running
18//   turn     once per turn with activity (logTurns, or count() in the mod's turn.complete hook): { hooks: { <event>: calls } }
19//   <other>  outcome rows from track(), e.g. merge-gate 'verdict'
20// Privacy: never put prompt, command, tool-input or matched-secret text in a row; lengths, kinds and counts only.
21
22const APPEND = 'mkdir -p "$HOME/.claude/mods" && printf "%s\\n" "$1" >> "$HOME/.claude/mods/metrics.jsonl"'
23
24
25const ctx = { ver: '', session: '', project: '' }
26const stats = new Map<string, number>()
27let writeFailed = false
28
29const message = (err: unknown) => (err instanceof Error ? err.message : String(err)).slice(0, 300)
30
31function write($: EngineInterface, mod: string, event: string, data: Record<string, unknown>): void {
32  void (async () => {
33    const t = new Date(await $.clock.now()).toISOString()
34    if (!ctx.project) ctx.project = (await $.session.cwd()).split('/').filter(Boolean).pop() ?? ''
35    const line = JSON.stringify({ v: 2, t, mod, event, ver: ctx.ver, session: ctx.session, project: ctx.project, ...data })
36    const { exitCode, stderr } = await $.process.run(['/bin/sh', '-c', APPEND, 'mod-metrics', line], { timeoutMs: 3000 })
37    if (exitCode !== 0) throw new Error(stderr.trim() || `exit ${exitCode}`)
38  })().catch((err: unknown) => {
39    if (writeFailed) return
40    writeFailed = true
41    $.ui.toast(`${mod}: metrics write failed (${message(err)})`)
42  })
43}
44
45// An outcome row: something the mod decided or did. Fire-and-forget.
46function track($: EngineInterface, mod: string, event: string, data: Record<string, unknown> = {}): void {
47  write($, mod, event, data)
48}
49
50async function loaded($: EngineInterface): Promise<void> {
51  const mod = $.plugin.name
52  ctx.session = await $.session.id().catch(() => '')
53  ctx.project = ''
54  try {
55    const manifest = JSON.parse(await $.fs.read(`${$.plugin.root}/.claude-plugin/plugin.json`)) as { version?: string }
56    ctx.ver = manifest.version ?? ''
57  } catch {
58    ctx.ver = '?'
59  }
60  write($, mod, 'loaded', {})
61}
62
63function flush($: EngineInterface): void {
64  const mod = $.plugin.name
65  if (!stats.size) return
66  const hooks = Object.fromEntries(stats)
67  stats.clear()
68  write($, mod, 'turn', { hooks })
69}
70
71// The engine allows one hook per event per plugin, and counts them by spelling. A mod that hooks
72// session.start or turn.complete itself calls count() in that hook, which writes the row; otherwise
73// it calls the matching helper once in register.
74function logLoaded(on: On): void {
75  on('session.start', async ($, e, next) => {
76    await loaded($)
77
78    return next(e)
79  })
80}
81
82function logTurns(on: On): void {
83  on('turn.complete', async ($, e, next) => {
84    flush($)
85
86    return next(e)
87  })
88}
89
90// First statement of every hook: counts the call into this turn's row. The engine only accepts
91// function literals as hooks, so calls are counted from inside rather than by wrapping.
92// In a session.start hook it also writes the loaded row; in a turn.complete hook it writes the turn row.
93function count($: EngineInterface, event: string): void {
94  stats.set(event, (stats.get(event) ?? 0) + 1)
95  if (event === 'session.start') void loaded($)
96  if (event === 'turn.complete') flush($)
97}
98// </metrics>
99
100// <money: generated from shared/money.ts by shared/sync.sh>
101// US dollars: three decimals under $1, where cents hide the cost of a cheap call; two from $1
102function usd(n: number): string {
103  return `$${Math.abs(n) < 1 ? n.toFixed(3) : n.toFixed(2)}`
104}
105// </money>
106
107// The folder a session or worktree belongs to: a worktree under <repo>/.claude/worktrees counts as the repo
108const projectOf = (cwd: string) => cwd.split('/.claude/worktrees/')[0].split('/').filter(Boolean).pop() ?? ''
109
110async function scan($: EngineInterface, days: number, project: string): Promise<Spend> {
111  const r = await $.process.run(['python3', '-I', `${$.plugin.root}/hooks/scan.py`, String(days)], { timeoutMs: 60_000 })
112  if (r.exitCode !== 0) throw new Error(r.stderr.trim().split('\n').pop() || `scan exited ${r.exitCode}`)
113  const agents = parse(r.stdout).filter(a => !project || a.project === project)
114  track($, 'agent-spend', 'scanned', { days, agents: agents.length, here: !!project })
115
116  return { agents, days, project }
117}
118
119export const register: Register = on => {
120  logTurns(on)
121
122  on('session.start', async ($, e, next) => {
123    count($, 'session.start')
124    await $.command.register({ name: 'spend', description: 'Subagent spend by model and agent type: /spend [days] [here]' })
125
126    return next(e)
127  })
128
129  on('command.run', { command: 'spend' }, async ($, e) => {
130    count($, 'command.run{spend}')
131    const args = e.args.trim().split(/\s+/).filter(Boolean)
132    const days = Math.max(1, Number(args.find(a => /^\d+$/.test(a)) ?? 7))
133    const project = args.includes('here') ? projectOf(await $.session.cwd()) : ''
134    try {
135      const s = await scan($, days, project)
136      await update($, spend, () => s)
137      void $.ui.open({ id: PANE, title: 'Agent spend' }).catch(() => undefined)
138
139      return { text: summary(s.agents, s.days, s.project) }
140    } catch (err) {
141      return { text: `agent-spend: could not read subagent transcripts (${err instanceof Error ? err.message : String(err)}).` }
142    }
143  })
144
145  on('ui.render', { component: 'Pane', requestId: PANE }, async ($, e) => {
146    count($, 'ui.render')
147    const { Box, Text } = $.ui.resolve(e)
148    const s = await read($, spend)
149    if (!s) return <Text dimColor>Run /spend [days] [here] to scan subagent spend.</Text>
150    if (!s.agents.length) return <Text dimColor>{summary(s.agents, s.days, s.project)}</Text>
151    const total = s.agents.reduce((n, a) => n + a.usd, 0)
152    const room = Math.max(1, (e.viewport?.rows ?? 24) - 14)
153    const row = (g: Group, key: string) => (
154      <Text key={key}>
155        {g.name.padEnd(16)} {String(g.agents).padStart(4)} {usd(g.usd).padStart(8)} <Text dimColor>{String(g.share).padStart(3)}%</Text>
156      </Text>
157    )
158
159    return (
160      <Box flexDirection="column">
161        <Text bold>
162          {usd(total)} · {s.agents.length} agents · last {s.days}d{s.project ? ` · ${s.project}` : ''}
163        </Text>
164        <Text dimColor>By model</Text>
165        {groups(s.agents, 'tier').map(g => row(g, `m-${g.name}`))}
166        <Text dimColor>By agent type</Text>
167        {groups(s.agents, 'type').map(g => row(g, `t-${g.name}`))}
168        <Text dimColor>Costliest</Text>
169        {costliest(s.agents, room).map((a, i) => (
170          <Text key={`c-${i}`} wrap="truncate">
171            {usd(a.usd).padStart(7)} {a.tier.padEnd(6)} {a.type} <Text dimColor>{a.desc}</Text>
172          </Text>
173        ))}
174      </Box>
175    )
176  })
177}
178

1// Pure helpers: no `$`, so tests call them directly.
2import type { Agent } from '../types'
3
4// <money: generated from shared/money.ts by shared/sync.sh>
5// US dollars: three decimals under $1, where cents hide the cost of a cheap call; two from $1
6function usd(n: number): string {
7  return `$${Math.abs(n) < 1 ? n.toFixed(3) : n.toFixed(2)}`
8}
9// </money>
10
11export function parse(stdout: string): Agent[] {
12  const out: Agent[] = []
13  for (const line of stdout.split('\n')) {
14    try {
15      const a = JSON.parse(line)
16      if (typeof a?.usd === 'number' && typeof a.tier === 'string') out.push(a)
17    } catch {}
18  }
19
20  return out
21}
22
23export type Group = { name: string; agents: number; usd: number; share: number }
24
25export function groups(agents: Agent[], key: 'tier' | 'type'): Group[] {
26  const total = agents.reduce((s, a) => s + a.usd, 0)
27  const by = new Map<string, Group>()
28  for (const a of agents) {
29    const g = by.get(a[key]) ?? { name: a[key], agents: 0, usd: 0, share: 0 }
30    g.agents += 1
31    g.usd += a.usd
32    by.set(a[key], g)
33  }
34
35  return [...by.values()].map(g => ({ ...g, share: total ? Math.round((g.usd * 100) / total) : 0 })).sort((a, b) => b.usd - a.usd)
36}
37
38export const costliest = (agents: Agent[], n: number) => [...agents].sort((a, b) => b.usd - a.usd).slice(0, n)
39
40export function summary(agents: Agent[], days: number, project: string): string {
41  const scope = `last ${days} day${days === 1 ? '' : 's'}${project ? ` in ${project}` : ''}`
42  if (!agents.length) return `No subagents ran in the ${scope}.`
43  const total = agents.reduce((s, a) => s + a.usd, 0)
44  const row = (g: Group) => `  ${g.name.padEnd(18)} ${String(g.agents).padStart(4)} agents  ${usd(g.usd).padStart(8)}  ${String(g.share).padStart(3)}%`
45
46  return [
47    `${agents.length} agents, ${scope}: ${usd(total)}`,
48    '',
49    'By model',
50    ...groups(agents, 'tier').map(row),
51    '',
52    'By agent type',
53    ...groups(agents, 'type').map(row),
54    '',
55    'Costliest',
56    ...costliest(agents, 5).map(a => `  ${usd(a.usd).padStart(7)}  ${a.tier.padEnd(6)} ${a.type.padEnd(16)} ${(a.tokens / 1e6).toFixed(1).padStart(5)}M  ${a.project}: ${a.desc}`),
57    '',
58    '$ are list-price estimates.',
59  ].join('\n')
60}
61

1export type Agent = { type: string; tier: string; usd: number; tokens: number; project: string; desc: string }
2export type Spend = { agents: Agent[]; days: number; project: string }
3
4declare module 'claude-code' {
5  interface PluginState {
6    'agent-spend': { spend: Spend | null }
7  }
8}
9