Turn Meter

1import type { On, PluginOptions, Register, TurnUsage } from 'claude-code'
2import { atom, read, update } from 'claude-code'
3
4import type { TurnSummary } from '../types'
5
6type Alert = 'toast' | 'notify' | 'off'
7
8type Settings = {
9  alert: Alert
10  alertAfterMs: number
11  showTokens: boolean
12}
13
14const COMMAND = 'turn-meter'
15const NARROW_COLUMNS = 60
16
17const last = atom({ plugin: 'turn-meter', key: 'last' } as const, null)
18const isHidden = atom({ plugin: 'turn-meter', key: 'isHidden' } as const, false)
19
20// The engine fills in the manifest's defaults; these only cover a value of the wrong type.
21const readSettings = (options: PluginOptions): Settings => {
22  const { alert, alertAfterSeconds, showTokens } = options
23  const seconds =
24    typeof alertAfterSeconds === 'number' && alertAfterSeconds > 0 ? alertAfterSeconds : 120
25
26  return {
27    alert: alert === 'notify' || alert === 'off' ? alert : 'toast',
28    alertAfterMs: seconds * 1000,
29    showTokens: typeof showTokens === 'boolean' ? showTokens : true,
30  }
31}
32
33const tokensIn = (usage: TurnUsage | undefined): number =>
34  usage === undefined
35    ? 0
36    : usage.input_tokens + usage.cache_read_input_tokens + usage.cache_creation_input_tokens
37
38// "3m 12s", "1m 05s" and "40s"; the short form drops the space: "3m12s".
39export const formatDuration = (ms: number, isShort = false): string => {
40  const total = Math.round(ms / 1000)
41  const minutes = Math.floor(total / 60)
42  const seconds = total % 60
43
44  if (minutes === 0) {
45    return `${seconds}s`
46  }
47
48  return `${minutes}m${isShort ? '' : ' '}${String(seconds).padStart(2, '0')}s`
49}
50
51// "6.3k" and "41.2k"; the short form rounds to whole thousands: "47k". The unit is picked after
52// rounding, so 999,999 reads "1M", never "1000k".
53export const formatTokens = (count: number, isShort = false): string => {
54  const thousands = isShort ? String(Math.round(count / 1000)) : (count / 1000).toFixed(1)
55
56  if (count >= 1000 && Number(thousands) < 1000) {
57    return `${thousands.replace(/\.0$/, '')}k`
58  }
59
60  if (count >= 1000) {
61    return `${(count / 1_000_000).toFixed(1).replace(/\.0$/, '')}M`
62  }
63
64  return String(count)
65}
66
67const plural = (count: number, word: string): string => `${count} ${word}${count === 1 ? '' : 's'}`
68
69const LEAD: Record<TurnSummary['reason'], string> = {
70  answer: '',
71  aborted: 'interrupted after ',
72  error: 'ended by API error after ',
73  refusal: 'refused after ',
74}
75
76const SHORT_LEAD: Record<TurnSummary['reason'], string> = {
77  answer: '',
78  aborted: 'interrupted ',
79  error: 'API error ',
80  refusal: 'refused ',
81}
82
83export const bandText = (turn: TurnSummary, showTokens: boolean, columns: number): string => {
84  const isShort = columns < NARROW_COLUMNS
85  const parts = [
86    `${(isShort ? SHORT_LEAD : LEAD)[turn.reason]}${formatDuration(turn.durationMs, isShort)}`,
87  ]
88
89  if (turn.reason !== 'refusal') {
90    const tools = plural(turn.tools + turn.subagentTools, 'tool')
91    const split =
92      isShort || turn.subagents === 0
93        ? ''
94        : ` (${turn.subagentTools} in ${plural(turn.subagents, 'subagent')})`
95    parts.push(`${tools}${split}`)
96  }
97
98  if (showTokens && turn.tokensIn + turn.tokensOut > 0) {
99    parts.push(
100      isShort
101        ? `${formatTokens(turn.tokensIn + turn.tokensOut, true)} tok`
102        : `${formatTokens(turn.tokensIn)} in / ${formatTokens(turn.tokensOut)} out`,
103    )
104  }
105
106  return `${isShort ? '' : 'Last turn: '}${parts.join(' · ')}`
107}
108
109export const register: Register = (on: On, options: PluginOptions): void => {
110  const settings = readSettings(options)
111
112  // The turn in progress. A reload in the middle of a turn starts these over,
113  // so that one turn comes out short; the last finished turn lives in $.state.
114  let tools = 0
115  let subagentTools = 0
116  let subagentIds = new Set<string>()
117  let subagentTokensIn = 0
118  let subagentTokensOut = 0
119
120  on('session.start', async ($, e, next) => {
121    await $.command.register({
122      name: COMMAND,
123      description: 'Show or hide the last-turn band above the prompt',
124    })
125
126    return next(e)
127  })
128
129  on('turn.start', (_$, e, next) => {
130    if (e.agentId === undefined) {
131      tools = 0
132      subagentTools = 0
133      subagentIds = new Set()
134      subagentTokensIn = 0
135      subagentTokensOut = 0
136    }
137
138    return next(e)
139  })
140
141  on('tool.call', (_$, e, next) => {
142    if (e.agentId === undefined) {
143      tools += 1
144    } else {
145      subagentTools += 1
146      subagentIds.add(e.agentId)
147    }
148
149    return next(e)
150  })
151
152  on('turn.complete', async ($, e, next) => {
153    if (e.agentId !== undefined) {
154      subagentIds.add(e.agentId)
155      subagentTokensIn += tokensIn(e.usage)
156      subagentTokensOut += e.usage?.output_tokens ?? 0
157
158      return next(e)
159    }
160
161    const turn: TurnSummary = {
162      durationMs: e.durationMs,
163      reason: e.reason,
164      tools,
165      subagentTools,
166      subagents: subagentIds.size,
167      tokensIn: tokensIn(e.usage) + subagentTokensIn,
168      tokensOut: (e.usage?.output_tokens ?? 0) + subagentTokensOut,
169    }
170    await update($, last, () => turn)
171
172    // An interrupted turn needs no alert: the person pressed Esc and is watching.
173    const isLong = turn.durationMs >= settings.alertAfterMs && turn.reason !== 'aborted'
174    if (isLong && settings.alert !== 'off') {
175      const text = `That turn took ${formatDuration(turn.durationMs)}`
176      // A notification nobody can receive (no terminal channel, the desktop app)
177      // falls back to a toast, so the alert is never lost.
178      const isSent =
179        settings.alert === 'notify' &&
180        (await $.ui.notify(text).then(
181          (sent) => sent.isSent,
182          () => false,
183        ))
184      if (!isSent) {
185        $.ui.toast(text)
186      }
187    }
188
189    return next(e)
190  })
191
192  on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
193    const turn = await read($, last)
194
195    if (e.props.hasSurvey || turn === null || (await read($, isHidden))) {
196      return next(e)
197    }
198
199    const { Box, Button, Text } = $.ui.resolve(e)
200    // The band is shared: what the mods after this one draw stays beneath the row.
201    const below = await next(e)
202
203    return (
204      <Box flexDirection="column">
205        <Box flexDirection="row" gap={1}>
206          <Text dimColor={true}>{bandText(turn, settings.showTokens, e.props.bodyColumns)}</Text>
207          <Button
208            key="hide"
209            label="Hide"
210            onPress={(): Promise<boolean> => update($, isHidden, () => true)}
211          />
212        </Box>
213        {below}
214      </Box>
215    )
216  })
217
218  on('command.run', { command: COMMAND }, async ($) => {
219    const hidden = await update($, isHidden, (value) => !value)
220    const hasTurn = (await read($, last)) !== null
221
222    if (hidden) {
223      return { text: 'Turn Meter band hidden. Run /turn-meter to show it again.' }
224    }
225
226    return {
227      text: hasTurn
228        ? 'Turn Meter band shown.'
229        : 'Turn Meter band shown. It appears after the first turn ends.',
230    }
231  })
232}
233

1/** Why a turn ended, as `turn.complete` reports it. */
2export type TurnReason = 'answer' | 'aborted' | 'error' | 'refusal'
3
4/** One finished main-loop turn, as the band shows it. */
5export type TurnSummary = {
6  durationMs: number
7  reason: TurnReason
8  /** Tool calls made by the main loop. */
9  tools: number
10  /** Tool calls made by subagents during the turn. */
11  subagentTools: number
12  /** Distinct subagents that ran during the turn. */
13  subagents: number
14  /** Input tokens: uncached, cache reads and cache writes, main loop and subagents. */
15  tokensIn: number
16  /** Output tokens, main loop and subagents. */
17  tokensOut: number
18}
19
20declare module 'claude-code' {
21  interface PluginState {
22    'turn-meter': { last: TurnSummary | null; isHidden: boolean }
23  }
24}
25