clippy

1import type { Register } from 'claude-code'
2
3import { createNotes } from './engine'
4import { observeCalls } from './hosts/observe'
5import { remindAtStop } from './hosts/stop'
6import { create as clippy } from './rules/clippy'
7
8export const register: Register = on => {
9  const rules = [clippy()]
10  const shared = createNotes()
11  observeCalls(on, rules)
12  remindAtStop(on, rules)
13}
14

1import type { ModelCompleteRequest, ModelCompleteResult, PluginOptions, ProcessRunResult, ToolCallEnvelope, ToolCallResult } from 'claude-code'
2
3// What a nudge may read when the turn stops. The engine forbids passing `$`
4// itself, so it hands over these functions instead.
5export type NudgeTools = {
6  contextPercent: () => Promise<number | undefined>
7  // The host clock and the session start, both in milliseconds since the epoch.
8  now: () => Promise<number>
9  sessionStartedAt: () => Promise<number>
10  // The variable NAMES listed in `.env.example` (never values, never `.env`),
11  // or undefined when the project has no `.env.example`.
12  envExampleNames: () => Promise<readonly string[] | undefined>
13  // One model call. It resolves with `isAnswered: false` instead of throwing
14  // when the model gives no text, so a nudge checks that before it speaks.
15  complete: (request: ModelCompleteRequest) => Promise<ModelCompleteResult>
16  // Runs a program (argv only, no shell) in `cwd`, with a time limit. It
17  // rejects when the program is missing or runs too long.
18  run: (argv: readonly string[], cwd: string) => Promise<ProcessRunResult>
19}
20
21export const RUN_TIMEOUT_MS = 10_000
22
23// One nudge: it may watch each tool call once the tool answered, and when
24// the turn stops it may name a one-line reminder for the person. The engine
25// shows each reminder as a toast. The model reads it only when the mod's host keeps it as a note for the next prompt (the bead nudges do; see PendingNotes). `options` are the
26// plugin's userConfig values, empty for a mod that declares none. `cwd` is
27// the session cwd ('' when the host gave none), for `repoPath`.
28export type Nudge = {
29  id: string
30  observe?: (e: ToolCallEnvelope, ran: ToolCallResult, cwd: string) => void
31  atStop: (tools: NudgeTools, options: PluginOptions) => string | undefined | Promise<string | undefined>
32}
33
34export const ENV_EXAMPLE = '.env.example'
35
36// Keeps only the NAME of each `NAME=value` line; the value is dropped here.
37export const envNames = (text: string): string[] =>
38  text.split('\n').flatMap(line => {
39    const name = /^\s*(?:export\s+)?([A-Za-z_]\w*)\s*=/.exec(line)?.[1]
40    return name === undefined ? [] : [name]
41  })
42
43const failed = (id: string, error: unknown): string =>
44  `${id}: skipped, ${error instanceof Error ? error.message : String(error)}`
45
46// The tools a host does not give. A nudge that calls one is logged and
47// skipped, and its tests fail: name what it uses in engine.json `needs`.
48const absent = (name: string) => (): Promise<never> =>
49  Promise.reject(new Error(`${name} is not given to this mod; name it in engine.json needs`))
50
51export const NO_TOOLS: NudgeTools = {
52  contextPercent: absent('contextPercent'),
53  now: absent('now'),
54  sessionStartedAt: absent('sessionStartedAt'),
55  envExampleNames: absent('envExampleNames'),
56  complete: absent('complete'),
57  run: absent('run'),
58}
59
60// Reminders waiting for the person's next prompt, so Claude reads them too.
61// Made once per mod and shared by the turn-end host and the prompt host. A
62// note is fixed text, a count or an id that matched the id pattern, never a
63// title or commit text.
64export type PendingNotes = { add: (note: string) => void; take: () => readonly string[] }
65
66export const createNotes = (): PendingNotes => {
67  let pending: readonly string[] = []
68  return {
69    add: note => {
70      pending = [...pending, note]
71    },
72    take: () => {
73      const taken = pending
74      pending = []
75      return taken
76    },
77  }
78}
79
80// Hands each finished tool call to the nudges that watch them. `log` closes
81// over the hook's `$`.
82export const observeAll = async (
83  nudges: readonly Nudge[],
84  e: ToolCallEnvelope,
85  ran: ToolCallResult,
86  cwd: string,
87  log: (text: string) => unknown,
88): Promise<void> => {
89  for (const nudge of nudges) {
90    try {
91      nudge.observe?.(e, ran, cwd)
92    } catch (error) {
93      await log(failed(nudge.id, error))
94    }
95  }
96}
97
98// Asks each nudge for its reminder as the turn stops and shows it as a toast.
99// `toast` and `log` close over the hook's `$`.
100export const remindAll = async (
101  nudges: readonly Nudge[],
102  tools: NudgeTools,
103  options: PluginOptions,
104  toast: (text: string) => unknown,
105  log: (text: string) => unknown,
106): Promise<readonly string[]> => {
107  let reminders: readonly string[] = []
108  for (const nudge of nudges) {
109    try {
110      const reminder = await nudge.atStop(tools, options)
111      if (reminder !== undefined) {
112        await toast(`${nudge.id}: ${reminder}`)
113        reminders = [...reminders, reminder]
114      }
115    } catch (error) {
116      await log(failed(nudge.id, error))
117    }
118  }
119  return reminders
120}
121

1import type { On } from 'claude-code'
2
3import { observeAll } from '../engine'
4import type { Nudge } from '../engine'
5
6// For nudges with `observe`: each tool call, once the tool answered.
7export const observeCalls = (on: On, nudges: readonly Nudge[]): void => {
8  on('tool.call', async ($, e, next) => {
9    const ran = await next(e)
10    const cwd = await $.session.cwd().catch(() => '')
11    await observeAll(nudges, e, ran, cwd, text => $.ui.log(text))
12    return ran
13  })
14}
15

1import type { On, PluginOptions } from 'claude-code'
2
3import { NO_TOOLS, remindAll } from '../engine'
4import type { Nudge } from '../engine'
5
6// The turn's end for nudges that read nothing but what they watched.
7export const remindAtStop = (on: On, nudges: readonly Nudge[], options: PluginOptions = {}): void => {
8  on('classic.Stop', async ($, e, next) => {
9    const tools = NO_TOOLS
10    await remindAll(nudges, tools, options, text => $.ui.toast(text), text => $.ui.log(text))
11    return next(e)
12  })
13}
14

1import type { Nudge } from '../engine'
2
3type Trigger = 'migration' | 'dockerfile' | 'workflow' | 'rm-rf'
4
5// The classic paperclip: it looks like you're doing X, want help? Each line
6// is a comment, never a block: the guard decides about rm -rf, clippy only talks.
7export const LINES: Readonly<Record<Trigger, string>> = {
8  migration: "It looks like you're writing a migration. Want me to remind you to back up first?",
9  dockerfile:
10    "It looks like you're editing a Dockerfile. Would you like me to remind you to pin the base image and keep secrets out of the layers?",
11  workflow:
12    "It looks like you're editing a GitHub Actions workflow. Want a tip? Pin third-party actions to a commit SHA and give the job the least permissions it needs.",
13  'rm-rf':
14    "It looks like you're deleting files with rm -rf. Want me to point out that there is no undo? The guard will ask anyway; I'm just a paperclip.",
15}
16
17const FILE_TOOLS = new Set(['Write', 'Edit', 'MultiEdit', 'NotebookEdit'])
18
19const pathTrigger = (path: string): Trigger | undefined => {
20  const parts = path.split('/')
21  const name = parts.at(-1) ?? ''
22  if (/^dockerfile(\..+)?$/i.test(name) || /\.dockerfile$/i.test(name)) return 'dockerfile'
23  if (/(^|\/)\.github\/workflows\/./.test(path)) return 'workflow'
24  if (parts.slice(0, -1).some(part => part.toLowerCase() === 'migrations')) return 'migration'
25  return undefined
26}
27
28// `rm` in command position with both a recursive and a force flag, in any
29// spelling (-rf, -fr, -Rf, -r -f, --recursive --force). `git rm` and the word
30// in an argument do not count.
31export const isRmRf = (command: string): boolean =>
32  command.split(/[;&|\n]+/).some(part => {
33    const words = part.trim().split(/\s+/)
34    const start = words[0] === 'sudo' ? 1 : 0
35    if (words[start] !== 'rm') return false
36    const flags = words.slice(start + 1).filter(word => word.startsWith('-'))
37    const short = flags.filter(flag => !flag.startsWith('--')).join('')
38    const isRecursive = /[rR]/.test(short) || flags.includes('--recursive')
39    const isForce = /f/.test(short) || flags.includes('--force')
40    return isRecursive && isForce
41  })
42
43const triggerOf = (e: Parameters<NonNullable<Nudge['observe']>>[0]): Trigger | undefined => {
44  if (FILE_TOOLS.has(e.tool)) {
45    const path = 'file_path' in e ? e.file_path : 'notebook_path' in e ? e.notebook_path : undefined
46    return typeof path === 'string' ? pathTrigger(path) : undefined
47  }
48  return e.tool === 'Bash' && isRmRf(e.command) ? 'rm-rf' : undefined
49}
50
51// One toast per session per trigger. At most one per turn (a stop): when
52// several triggers fire in one turn the first speaks and the rest wait, in
53// order, for the next turn's stop.
54export const create = (): Nudge => {
55  const spoken = new Set<Trigger>()
56  let waiting: readonly Trigger[] = []
57
58  return {
59    id: 'clippy',
60    observe: e => {
61      const trigger = triggerOf(e)
62      if (trigger !== undefined && !spoken.has(trigger) && !waiting.includes(trigger)) waiting = [...waiting, trigger]
63    },
64    atStop: () => {
65      const [next, ...rest] = waiting
66      if (next === undefined) return undefined
67      waiting = rest
68      spoken.add(next)
69      return LINES[next]
70    },
71  }
72}
73