next-steps

1import { atom, read, update } from 'claude-code'
2import type { EngineInterface, On, Register } from 'claude-code'
3
4import { SYSTEM, parse, prompt } from './suggest.ts'
5
6// The smallest model: one short call per answered turn
7const MODEL = 'claude-haiku-5-5'
8const OFF_KEY = 'off'
9
10const suggestions = atom({ plugin: 'next-steps', key: 'suggestions' } as const, [])
11
12const isOff = async ($: EngineInterface) => (await $.store.get(OFF_KEY).catch(() => false)) === true
13
14// <metrics: generated from shared/metrics.ts by shared/sync.sh>
15// Shared mod metrics (schema v2). Source of truth: ~/.claude/mods/shared/metrics.ts.
16// shared/sync.sh inlines it between the metrics markers in each mod's register.tsx (the engine only lets $
17// into functions declared in the same file). Edit here, run sync.sh, never edit an inlined copy.
18//
19// Rows appended to ~/.claude/mods/metrics.jsonl, all with { v: 2, t, mod, event, ver, session, project }:
20//   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
21//   turn     once per turn with activity (logTurns, or count() in the mod's turn.complete hook): { hooks: { <event>: calls } }
22//   <other>  outcome rows from track(), e.g. merge-gate 'verdict'
23// Privacy: never put prompt, command, tool-input or matched-secret text in a row; lengths, kinds and counts only.
24
25const APPEND = 'mkdir -p "$HOME/.claude/mods" && printf "%s\\n" "$1" >> "$HOME/.claude/mods/metrics.jsonl"'
26
27
28const ctx = { ver: '', session: '', project: '' }
29const stats = new Map<string, number>()
30let writeFailed = false
31
32const message = (err: unknown) => (err instanceof Error ? err.message : String(err)).slice(0, 300)
33
34function write($: EngineInterface, mod: string, event: string, data: Record<string, unknown>): void {
35  void (async () => {
36    const t = new Date(await $.clock.now()).toISOString()
37    if (!ctx.project) ctx.project = (await $.session.cwd()).split('/').filter(Boolean).pop() ?? ''
38    const line = JSON.stringify({ v: 2, t, mod, event, ver: ctx.ver, session: ctx.session, project: ctx.project, ...data })
39    const { exitCode, stderr } = await $.process.run(['/bin/sh', '-c', APPEND, 'mod-metrics', line], { timeoutMs: 3000 })
40    if (exitCode !== 0) throw new Error(stderr.trim() || `exit ${exitCode}`)
41  })().catch((err: unknown) => {
42    if (writeFailed) return
43    writeFailed = true
44    $.ui.toast(`${mod}: metrics write failed (${message(err)})`)
45  })
46}
47
48// An outcome row: something the mod decided or did. Fire-and-forget.
49function track($: EngineInterface, mod: string, event: string, data: Record<string, unknown> = {}): void {
50  write($, mod, event, data)
51}
52
53async function loaded($: EngineInterface): Promise<void> {
54  const mod = $.plugin.name
55  ctx.session = await $.session.id().catch(() => '')
56  ctx.project = ''
57  try {
58    const manifest = JSON.parse(await $.fs.read(`${$.plugin.root}/.claude-plugin/plugin.json`)) as { version?: string }
59    ctx.ver = manifest.version ?? ''
60  } catch {
61    ctx.ver = '?'
62  }
63  write($, mod, 'loaded', {})
64}
65
66function flush($: EngineInterface): void {
67  const mod = $.plugin.name
68  if (!stats.size) return
69  const hooks = Object.fromEntries(stats)
70  stats.clear()
71  write($, mod, 'turn', { hooks })
72}
73
74// The engine allows one hook per event per plugin, and counts them by spelling. A mod that hooks
75// session.start or turn.complete itself calls count() in that hook, which writes the row; otherwise
76// it calls the matching helper once in register.
77function logLoaded(on: On): void {
78  on('session.start', async ($, e, next) => {
79    await loaded($)
80
81    return next(e)
82  })
83}
84
85function logTurns(on: On): void {
86  on('turn.complete', async ($, e, next) => {
87    flush($)
88
89    return next(e)
90  })
91}
92
93// First statement of every hook: counts the call into this turn's row. The engine only accepts
94// function literals as hooks, so calls are counted from inside rather than by wrapping.
95// In a session.start hook it also writes the loaded row; in a turn.complete hook it writes the turn row.
96function count($: EngineInterface, event: string): void {
97  stats.set(event, (stats.get(event) ?? 0) + 1)
98  if (event === 'session.start') void loaded($)
99  if (event === 'turn.complete') flush($)
100}
101// </metrics>
102
103export const register: Register = on => {
104  let lastAsked = ''
105
106  on('session.start', async ($, e, next) => {
107    count($, 'session.start')
108    await $.command.register({ name: 'next', description: 'Next-prompt suggestions after each turn: /next off | on' })
109
110    return next(e)
111  })
112
113  on('command.run', { command: 'next' }, async ($, e) => {
114    count($, 'command.run{next}')
115    const arg = e.args.trim()
116    if (arg === 'off' || arg === 'on') {
117      await $.store.set(OFF_KEY, arg === 'off')
118      if (arg === 'off') await update($, suggestions, () => [])
119    }
120
121    return { text: `next-steps is ${(await isOff($)) ? 'off' : 'on'}.` }
122  })
123
124  on('prompt.submit', async ($, e, next) => {
125    count($, 'prompt.submit')
126    if (e.origin.kind === 'composer' || e.origin.kind === 'bridge') lastAsked = e.text
127    await update($, suggestions, () => [])
128
129    return next(e)
130  }).catch(($, e, next) => next(e))
131
132  on('turn.complete', async ($, e, next) => {
133    count($, 'turn.complete')
134    const done = await next(e)
135    if (e.agentId !== undefined || e.reason !== 'answer' || !e.answer.trim() || (await isOff($))) return done
136
137    // Off the turn's path: the suggestions arrive a moment after the answer
138    void (async () => {
139      const r = await $.model.complete({ model: MODEL, system: SYSTEM, prompt: prompt(lastAsked, e.answer), maxTokens: 120, timeoutMs: 15_000 })
140      const u = r.usage
141      track($, 'next-steps', 'shown', { ok: r.isAnswered, usd: u ? (u.input_tokens * 0.1 + u.output_tokens * 0.5) / 1e6 : 0, tokens: u ? u.input_tokens + u.output_tokens : 0 })
142      if (r.isAnswered) await update($, suggestions, () => parse(r.text))
143    })().catch(() => undefined)
144
145    return done
146  })
147
148  on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
149    count($, 'ui.render')
150    const list = await read($, suggestions)
151    if (list.length === 0 || e.props.hasSurvey || e.props.isWorking) return next(e)
152    const { Box, Text, Button } = $.ui.resolve(e)
153    const below = await next(e)
154
155    const width = Math.max(20, e.props.bodyColumns)
156
157    // One row per suggestion so long ones wrap instead of being cut off
158    return (
159      <Box flexDirection="column">
160        <Box flexDirection="row" gap={1} width={width}>
161          <Text dimColor>Next (press a number, 0 hides):</Text>
162          <Button key="hide" hotkey="0" plain label="✕" role="dismiss" onPress={() => update($, suggestions, () => [])} />
163        </Box>
164        {list.map((s, i) => (
165          <Box key={`row${i + 1}`} flexDirection="row" gap={1} width={width}>
166            <Button
167              key={`s${i + 1}`}
168              hotkey={String(i + 1)}
169              label={String(i + 1)}
170              onPress={async () => {
171                track($, 'next-steps', 'clicked', { n: i + 1 })
172                await $.prompt.fill({ text: s, mode: 'replace' })
173                await update($, suggestions, () => [])
174              }}
175            />
176            <Text wrap="wrap">{s}</Text>
177          </Box>
178        ))}
179        {below}
180      </Box>
181    )
182  })
183}
184

1// Pure helpers: no `$`, so tests call them directly.
2
3export const SYSTEM = [
4  "You suggest what the user of a coding agent will most likely type next.",
5  'Reply with 2 or 3 lines, one suggestion per line, nothing else: no numbering, quotes or preamble.',
6  "Each line is a short prompt in the user's own voice (under 12 words), concrete to this conversation.",
7  'Prefer the obvious next step: approve or merge what was proposed, answer a question the agent asked, run or check something.',
8].join(' ')
9
10export function prompt(asked: string, answer: string): string {
11  const clip = (s: string, n: number) => (s.length > n ? `${s.slice(0, n)}…` : s)
12
13  return `The user asked:\n${clip(asked, 1500)}\n\nThe agent replied:\n${clip(answer, 4000)}\n\nThe user's likely next prompts:`
14}
15
16export function parse(text: string): string[] {
17  return text
18    .split('\n')
19    .map(l => l.replace(/^\s*(?:[-*•]|\d+[.)])\s*/, '').replace(/^["'`]|["'`]$/g, '').trim())
20    .filter(l => l.length > 2 && l.length <= 120)
21    .slice(0, 3)
22}
23

1export type Suggestions = string[]
2
3declare module 'claude-code' {
4  interface PluginState {
5    'next-steps': { suggestions: Suggestions }
6  }
7}
8