peek

1import { atom, read, update } from 'claude-code'
2import type { Register, ToolCallInput, TurnUsage } from 'claude-code'
3
4import type { PeekCall, PeekToolTime } from '../types'
5
6const calls = atom({ plugin: 'peek', key: 'calls' } as const, [] as PeekCall[])
7const background = atom({ plugin: 'peek', key: 'background' } as const, [] as string[])
8const turn = atom({ plugin: 'peek', key: 'turn' } as const, [] as PeekToolTime[])
9const tick = atom({ plugin: 'peek', key: 'tick' } as const, 0)
10
11const TICK_MS = 30_000
12const LONG_TURN_MS = 30 * 60_000
13const LABEL_MAX = 48
14const TASK_ID = /<task-id>([^<]+)<\/task-id>/
15const AGENT_TOOLS = new Set(['Agent', 'Task'])
16
17// peek only watches: every hook passes its event on unchanged, and the one
18// rewrite is the spinner's suffix. Nothing here spawns a process.
19export const register: Register = on => {
20  on('session.start', async ($, e, next) => {
21    // A reload drops the hooks that would have closed the calls in flight.
22    await update($, calls, () => [])
23    $.clock.every(TICK_MS, () => {
24      void update($, tick, n => n + 1)
25    })
26    return next(e)
27  })
28
29  on('turn.start', async ($, e, next) => {
30    await update($, turn, () => [])
31    return next(e)
32  })
33
34  on('tool.call', async ($, e, next) => {
35    const call: PeekCall = {
36      id: e.tool_use_id,
37      tool: e.tool,
38      label: labelOf(e),
39      startedAt: await $.clock.now(),
40      agentId: e.agentId ?? null,
41    }
42    await update($, calls, list => [...list, call])
43    try {
44      const ran = await next(e)
45      const taskId = ran.deny === undefined ? backgroundTaskId(ran.result) : null
46      if (taskId !== null) {
47        await update($, background, ids => [...ids, taskId])
48      }
49      if (call.agentId === null) {
50        const elapsed = (await $.clock.now()) - call.startedAt
51        await update($, turn, times => addTime(times, call.tool, elapsed))
52      }
53      return ran
54    } finally {
55      await update($, calls, list => list.filter(one => one.id !== call.id))
56    }
57  })
58
59  on('prompt.submit', async ($, e, next) => {
60    const done = e.origin?.kind === 'task-notification' ? TASK_ID.exec(e.text)?.[1] : undefined
61    if (done !== undefined) {
62      await update($, background, ids => ids.filter(id => id !== done))
63    }
64    return next(e)
65  })
66
67  // The turn's end carries the engine's own list of background work: the
68  // authoritative count, so a task that ended without a notification (stopped,
69  // or folded into a running turn) never lingers as "1 bg".
70  on('classic.Stop', async ($, e, next) => {
71    const ran = await next(e)
72    if (e.background_tasks !== undefined) {
73      const shells = e.background_tasks.filter(task => task.type === 'shell').map(task => task.id)
74      await update($, background, () => shells)
75    }
76    return ran
77  })
78
79  on('ui.render', { component: 'Spinner' }, async ($, e, next) => {
80    const list = await read($, calls)
81    const running = (await read($, background)).length
82    await read($, tick) // subscribes the drawing to the age tick
83    const detail = describe(list, running, await $.clock.now())
84    if (detail === null) {
85      return next(e)
86    }
87    return next({ ...e, props: { ...e.props, suffix: `${e.props.suffix} ${detail}` } })
88  })
89
90  on('turn.complete', async ($, e, next) => {
91    const ran = await next(e)
92    if (e.agentId !== undefined) {
93      return ran
94    }
95    // Nothing of the main loop runs past its turn; a reload may have left one.
96    await update($, calls, list => list.filter(one => one.agentId !== null))
97    if (e.durationMs < LONG_TURN_MS) {
98      return ran
99    }
100    const line = breakdown(e.durationMs, await read($, turn), e.usage)
101    // next() answers the answer's own text; any other text is a line drawn
102    // beneath it. A line a plugin below already set stays, ours goes after it.
103    return { ...ran, text: ran.text === e.answer ? line : `${ran.text}\n${line}` }
104  })
105}
106
107// describe is what the spinner adds: the main loop's oldest call in flight
108// (its age once it has run a tick), foreground agents, background tasks.
109function describe(list: readonly PeekCall[], running: number, now: number): string | null {
110  const main = list.filter(one => one.agentId === null)
111  const agents = main.filter(one => AGENT_TOOLS.has(one.tool)).length
112  const parts: string[] = []
113  const oldest = main.reduce<PeekCall | null>((first, one) => (first === null || one.startedAt < first.startedAt ? one : first), null)
114  if (oldest !== null) {
115    const age = now - oldest.startedAt
116    parts.push(age >= TICK_MS ? `${oldest.label} · ${duration(age)}` : oldest.label)
117    if (main.length > 1) {
118      parts.push(`+${main.length - 1} more`)
119    }
120  }
121  if (agents > 0) {
122    parts.push(agents === 1 ? '1 agent' : `${agents} agents`)
123  }
124  if (running > 0) {
125    parts.push(`${running} bg`)
126  }
127  return parts.length === 0 ? null : parts.join(' · ')
128}
129
130function breakdown(durationMs: number, times: readonly PeekToolTime[], usage: TurnUsage | undefined): string {
131  const tools = [...times]
132    .sort((a, b) => b.ms - a.ms)
133    .slice(0, 4)
134    .map(one => `${one.tool} ${duration(one.ms)} ×${one.calls}`)
135  const parts = [`Turn ${duration(durationMs)}`]
136  if (tools.length > 0) {
137    parts.push(`tool time: ${tools.join(', ')}`)
138  }
139  if (usage !== undefined) {
140    const input = usage.input_tokens + usage.cache_read_input_tokens + usage.cache_creation_input_tokens
141    parts.push(`tokens: ${count(input)} in (${count(usage.cache_read_input_tokens)} cached) / ${count(usage.output_tokens)} out`)
142  }
143  return parts.join(' — ')
144}
145
146function addTime(times: readonly PeekToolTime[], tool: string, ms: number): PeekToolTime[] {
147  const found = times.find(one => one.tool === tool)
148  if (found === undefined) {
149    return [...times, { tool, ms, calls: 1 }]
150  }
151  return times.map(one => (one.tool === tool ? { tool, ms: one.ms + ms, calls: one.calls + 1 } : one))
152}
153
154function labelOf(e: ToolCallInput): string {
155  if ('description' in e && typeof e.description === 'string' && e.description.trim() !== '') {
156    return clip(e.description.trim())
157  }
158  if (e.tool === 'Bash') {
159    return clip(e.command.trim().split('\n')[0] ?? '')
160  }
161  const tool = e.tool.startsWith('mcp__') ? (e.tool.split('__').at(-1) ?? e.tool) : e.tool
162  if ('file_path' in e && typeof e.file_path === 'string') {
163    return clip(`${tool} ${e.file_path.split('/').at(-1) ?? ''}`)
164  }
165  return tool
166}
167
168function backgroundTaskId(result: unknown): string | null {
169  if (typeof result !== 'object' || result === null || !('backgroundTaskId' in result)) {
170    return null
171  }
172  return typeof result.backgroundTaskId === 'string' ? result.backgroundTaskId : null
173}
174
175function clip(text: string): string {
176  return text.length <= LABEL_MAX ? text : `${text.slice(0, LABEL_MAX - 1)}…`
177}
178
179function duration(ms: number): string {
180  const minutes = Math.floor(ms / 60_000)
181  if (minutes < 1) {
182    return `${Math.floor(ms / 1000)}s`
183  }
184  if (minutes < 60) {
185    return `${minutes}m`
186  }
187  const rest = minutes % 60
188  return rest === 0 ? `${Math.floor(minutes / 60)}h` : `${Math.floor(minutes / 60)}h ${rest}m`
189}
190
191function count(tokens: number): string {
192  if (tokens >= 1_000_000) {
193    return `${(tokens / 1_000_000).toFixed(1)}M`
194  }
195  if (tokens >= 1000) {
196    return `${Math.round(tokens / 1000)}k`
197  }
198  return String(tokens)
199}
200

1// peek's state contract: the session values its hooks keep in $.state.
2
3/** A tool call in flight, as the spinner names it. */
4export type PeekCall = {
5  id: string
6  tool: string
7  /** The call's own description, else its tool and a head of its input. */
8  label: string
9  startedAt: number
10  /** The subagent's loop; null on the main loop. */
11  agentId: string | null
12}
13
14/** One tool's share of the running main-loop turn. */
15export type PeekToolTime = { tool: string; ms: number; calls: number }
16
17declare module 'claude-code' {
18  interface PluginState {
19    peek: {
20      calls: PeekCall[]
21      /** Background task ids still running (Bash run_in_background). */
22      background: string[]
23      turn: PeekToolTime[]
24      /** Bumped every 30 s so the spinner's ages redraw. */
25      tick: number
26    }
27  }
28}
29