agent-monitor

1import { atom, read, update } from 'claude-code'
2import type { EngineInterface, Register, TurnUsage } from 'claude-code'
3
4import type { AgentRun } from '../types'
5
6const PANE = 'agent-monitor'
7const TITLE = 'Agents'
8const HISTORY_KEY = 'history'
9const KEEP = 60
10
11const runs = atom({ plugin: 'agent-monitor', key: 'runs' } as const, [])
12const tick = atom({ plugin: 'agent-monitor', key: 'tick' } as const, 0)
13const showAll = atom({ plugin: 'agent-monitor', key: 'showAll' } as const, false)
14
15function clip(text: string, n: number): string {
16  const one = text.replace(/\s+/g, ' ').trim()
17  return one.length > n ? one.slice(0, n - 1) + '…' : one
18}
19
20function base(path: unknown): string {
21  return typeof path === 'string' ? path.split('/').filter(Boolean).pop() ?? path : ''
22}
23
24// One short line saying what a tool call is doing, for the "now" row.
25function describeCall(tool: string, input: Record<string, unknown>): string {
26  const s = (k: string) => (typeof input[k] === 'string' ? (input[k] as string) : '')
27  switch (tool) {
28    case 'Bash':
29      return `$ ${clip(s('command'), 70)}`
30    case 'Read':
31      return `reading ${base(input.file_path)}`
32    case 'Edit':
33    case 'Write':
34    case 'NotebookEdit':
35      return `editing ${base(input.file_path ?? input.notebook_path)}`
36    case 'Grep':
37      return `searching "${clip(s('pattern'), 40)}"`
38    case 'Glob':
39      return `finding ${clip(s('pattern'), 40)}`
40    case 'WebFetch':
41      return `fetching ${clip(s('url'), 60)}`
42    case 'WebSearch':
43      return `searching web "${clip(s('query'), 40)}"`
44    case 'Agent':
45      return `spawning: ${clip(s('description'), 50)}`
46    default:
47      return tool.startsWith('mcp__') ? tool.split('__').slice(1).join(' › ') : tool
48  }
49}
50
51function totalTokens(u: TurnUsage | undefined): number | null {
52  if (!u) return null
53  return u.input_tokens + u.output_tokens + u.cache_read_input_tokens + u.cache_creation_input_tokens
54}
55
56function fmtTokens(n: number | null): string {
57  if (n === null) return ''
58  return n >= 1_000_000 ? `${(n / 1_000_000).toFixed(1)}M tok` : n >= 1000 ? `${Math.round(n / 1000)}k tok` : `${n} tok`
59}
60
61function fmtSecs(ms: number): string {
62  const s = Math.max(0, Math.round(ms / 1000))
63  return s >= 3600 ? `${Math.floor(s / 3600)}h${Math.floor((s % 3600) / 60)}m` : s >= 60 ? `${Math.floor(s / 60)}m${s % 60}s` : `${s}s`
64}
65
66function shortModel(model: string): string {
67  const m = model.toLowerCase()
68  for (const name of ['opus', 'sonnet', 'haiku', 'fable']) if (m.includes(name)) return name
69  return model
70}
71
72async function refreshStatus($: EngineInterface) {
73  const list = await read($, runs)
74  const running = list.filter(r => r.status === 'running').length
75  $.ui.status(running > 0 ? `⚙ ${running} subagent${running === 1 ? '' : 's'} running` : undefined)
76}
77
78export const register: Register = on => {
79  let opened = false
80  let ticker: { cancel: () => void } | null = null
81
82  on('session.start', async ($, e, next) => {
83    await $.command.register({
84      name: 'subagents',
85      description: 'Open the subagent monitor: what each subagent is doing, its model, time and tokens',
86      argumentHint: '[clear]',
87    })
88    const saved = await $.store.get(HISTORY_KEY)
89    if (Array.isArray(saved)) {
90      await update($, runs, list => (list.length > 0 ? list : (saved as AgentRun[]).slice(-KEEP)))
91    }
92
93    return next(e)
94  })
95
96  on('command.run', { command: 'subagents' }, async ($, e) => {
97    if (e.args.trim() === 'clear') {
98      await update($, runs, list => list.filter(r => r.status === 'running'))
99      await $.store.set(HISTORY_KEY, [])
100      return { text: 'Agent history cleared.' }
101    }
102    opened = true
103    await $.ui.open({ id: PANE, title: TITLE })
104    const list = await read($, runs)
105    const running = list.filter(r => r.status === 'running').length
106
107    return { text: `Agent monitor opened: ${running} running, ${list.length - running} finished.` }
108  })
109
110  on('agent.spawn', async ($, e, next) => {
111    const started = await next(e)
112    if (started.deny !== undefined || started.agentId === undefined) return started
113
114    const run: AgentRun = {
115      id: started.agentId,
116      description: e.description || e.subagentType,
117      type: e.subagentType,
118      model: shortModel(started.model || e.model || e.parentModel),
119      status: 'running',
120      startedAt: await $.clock.now(),
121      endedAt: null,
122      tools: 0,
123      doing: 'starting',
124      tokens: null,
125      summary: null,
126    }
127    await update($, runs, list => [...list.filter(r => r.id !== run.id), run].slice(-KEEP))
128
129    if (!opened) {
130      opened = true
131      void $.ui.open({ id: PANE, title: TITLE })
132    }
133    if (ticker === null) {
134      ticker = $.clock.every(5000, () => {
135        void (async () => {
136          const list = await read($, runs)
137          if (!list.some(r => r.status === 'running')) {
138            ticker?.cancel()
139            ticker = null
140            return
141          }
142          await update($, tick, n => n + 1)
143        })()
144      })
145    }
146    await refreshStatus($)
147
148    return started
149  }).catch(($, e, next) => next(e))
150
151  on('tool.call', async ($, e, next) => {
152    const agentId = e.agentId
153    if (agentId !== undefined) {
154      const doing = describeCall(String(e.tool), e as unknown as Record<string, unknown>)
155      void update($, runs, list =>
156        list.some(r => r.id === agentId)
157          ? list.map(r => (r.id === agentId ? { ...r, tools: r.tools + 1, doing } : r))
158          : list,
159      )
160    }
161
162    return next(e)
163  }).catch(($, e, next) => next(e))
164
165  on('turn.complete', async ($, e, next) => {
166    const agentId = e.agentId
167    if (agentId !== undefined) {
168      const now = await $.clock.now()
169      const status = e.isAborted ? 'stopped' : e.reason === 'error' || e.reason === 'refusal' ? 'failed' : 'done'
170      const tokens = totalTokens(e.usage)
171      const summary = e.answer ? clip(e.answer, 160) : null
172      let isOurs = false
173      await update($, runs, list =>
174        list.map(r => {
175          if (r.id !== agentId) return r
176          isOurs = true
177          return { ...r, status, endedAt: now, doing: null, summary, tokens: (r.tokens ?? 0) + (tokens ?? 0) || null }
178        }),
179      )
180      if (isOurs) {
181        const list = await read($, runs)
182        await $.store.set(HISTORY_KEY, list.filter(r => r.status !== 'running').slice(-KEEP))
183        await refreshStatus($)
184        if (status === 'failed') $.ui.toast(`Subagent failed: ${clip(list.find(r => r.id === agentId)?.description ?? '', 50)}`)
185      }
186    }
187
188    return next(e)
189  })
190
191
192  on('ui.render', { component: 'Pane', requestId: PANE }, async ($, e) => {
193    const { Box, Text, Button } = $.ui.resolve(e)
194    await read($, tick)
195    const now = await $.clock.now()
196    const list = await read($, runs)
197    const isAll = await read($, showAll)
198    const running = list.filter(r => r.status === 'running')
199    const finished = list.filter(r => r.status !== 'running').reverse()
200    const shown = isAll ? finished : finished.slice(0, 8)
201    const width = Math.max(20, e.props.bodyColumns ?? 40)
202    const mark = { done: '✓', failed: '✗', stopped: '■', running: '●' } as const
203    const tone = { done: 'success', failed: 'error', stopped: 'warning', running: 'claude' } as const
204
205    const row = (r: AgentRun) => (
206      <Box key={`r-${r.id}`} flexDirection="column" marginBottom={1}>
207        <Button key={`v-${r.id}`} plain onPress={() => void $.ui.view({ agentId: r.id })}>
208          <Text color={tone[r.status]}>{mark[r.status]} </Text>
209          {clip(r.description, width - 4)}
210        </Button>
211        <Text dimColor wrap="truncate">
212          {'  '}
213          {r.type} · {r.model} · {fmtSecs((r.endedAt ?? now) - r.startedAt)} · {r.tools} tools
214          {r.tokens ? ` · ${fmtTokens(r.tokens)}` : ''}
215        </Text>
216        {r.doing && (
217          <Text color="suggestion" wrap="truncate">
218            {'  now: '}
219            {r.doing}
220          </Text>
221        )}
222        {r.summary && r.status !== 'running' && (
223          <Text dimColor wrap="truncate">
224            {'  → '}
225            {r.summary}
226          </Text>
227        )}
228      </Box>
229    )
230
231    return (
232      <Box flexDirection="column">
233        <Text bold>Running ({running.length})</Text>
234        {running.length === 0 && <Text dimColor>No subagents running.</Text>}
235        {running.map(row)}
236        <Box marginTop={1}>
237          <Text bold>Finished ({finished.length})</Text>
238        </Box>
239        {finished.length === 0 && <Text dimColor>Nothing yet. Subagents appear here as Claude spawns them.</Text>}
240        {shown.map(row)}
241        <Box flexDirection="row" gap={1}>
242          {finished.length > 8 && (
243            <Button key="all" label={isAll ? 'Show fewer' : `Show all ${finished.length}`} onPress={() => void update($, showAll, v => !v)} />
244          )}
245          {finished.length > 0 && (
246            <Button
247              key="clear"
248              label="Clear history"
249              onPress={async () => {
250                await update($, runs, l => l.filter(r => r.status === 'running'))
251                await $.store.set(HISTORY_KEY, [])
252              }}
253            />
254          )}
255        </Box>
256        <Text dimColor>Press a row to open that agent's transcript.</Text>
257      </Box>
258    )
259  })
260}
261

1export type AgentRunStatus = 'running' | 'done' | 'failed' | 'stopped'
2
3export type AgentRun = {
4  id: string
5  description: string
6  type: string
7  model: string
8  status: AgentRunStatus
9  startedAt: number
10  endedAt: number | null
11  tools: number
12  doing: string | null
13  tokens: number | null
14  summary: string | null
15}
16
17declare module 'claude-code' {
18  interface PluginState {
19    'agent-monitor': { runs: AgentRun[]; tick: number; showAll: boolean }
20  }
21}
22