mod-scout

1import type { EngineInterface, Register } from 'claude-code'
2
3type Macro = { name: string; text: string; createdAt: number }
4type Count = { n: number; text: string; at: number }
5type Rule = { id: string; command: string; test: RegExp; tip: string }
6
7// Origins that are a person typing: the terminal, Remote Control (phone), an app host.
8const PERSON = new Set(['composer', 'bridge', 'sdk'])
9
10// Each rule fires only when its command is installed, at most once a session.
11const RULES: readonly Rule[] = [
12  { id: 'tokens', command: 'tokens', test: /\b(tokens?|cost|spend|usage|limit|expensive|cheaper|quota)\b/i, tip: '/tokens shows where tokens go and what to change' },
13  { id: 'subagents', command: 'subagents', test: /\b(sub-?agents?|agents? (are|is) (doing|running)|background (jobs?|agents?))\b/i, tip: '/subagents shows every subagent and what it is doing now' },
14  { id: 'todo', command: 'todo', test: /\b(remind me|don'?t forget|to-?do|later i (need|have) to|note to self)\b/i, tip: '/todo <text> keeps it on your list across sessions' },
15  { id: 'eod', command: 'eod', test: /\b(stand-?up|end of (the )?day|what did i (do|get done)|daily (summary|report)|status update)\b/i, tip: '/eod prints today\'s work log for free' },
16  { id: 'pickup', command: 'pickup', test: /\b(where (was i|did we leave)|pick up|continue (from )?(yesterday|last time)|resume (the|my) work)\b/i, tip: '/pickup continues from the last /handoff note' },
17  { id: 'handoff', command: 'handoff', test: /\b(wrap(ping)? up|calling it a day|done for (today|the day)|stop(ping)? for now|tomorrow i)\b/i, tip: '/handoff saves where you are so the next session resumes exactly here' },
18  { id: 'podium', command: 'podium', test: /\b(codex|gemini|muse|other agents?|second opinion|cross-?review)\b/i, tip: '/podium hands the job to another agent CLI and tracks it' },
19  { id: 'grounded', command: 'grounded', test: /\b(best practices?|ci gate|repo (structure|hygiene)|engineering (standards|practices)|agents\.md|claude\.md)\b/i, tip: '/grounded lists practices that fit this repo, with sources' },
20  { id: 'clarify', command: 'clarify', test: /\b(ask me (questions|first)|clarify|before you start)\b/i, tip: '/clarify now <task> makes Claude ask its questions first' },
21]
22
23const STOP = new Set('a an the to of in on for and or but is are be it this that with my me i you we please can could would should do make just then also from at by as so what how'.split(' '))
24
25function normalize(text: string): string {
26  return text.toLowerCase().replace(/\d+/g, '#').replace(/[^\w#\s]/g, ' ').replace(/\s+/g, ' ').trim().slice(0, 200)
27}
28
29function slugOf(text: string, taken: ReadonlySet<string>): string {
30  const words = normalize(text).replace(/#/g, '').split(' ').filter(w => w.length > 1 && !STOP.has(w))
31  const base = (words.slice(0, 2).join('-') || 'macro').slice(0, 24)
32  let name = base
33  for (let i = 2; taken.has(name); i++) name = `${base}-${i}`
34  return name
35}
36
37// Independent items in one prompt: 3+ numbered or bulleted lines.
38function listCount(text: string): number {
39  return text.match(/^\s*([-*•]|\d+[.)])\s+\S/gm)?.length ?? 0
40}
41
42const TASK = /\b(build|implement|add|create|fix|refactor|migrate|write|design|set ?up|debug|optimi[sz]e|integrate|ship|deploy)\b/i
43
44async function commandNames($: EngineInterface): Promise<Set<string>> {
45  const list = await $.command.list().catch(() => [])
46  return new Set(list.map(c => c.name))
47}
48
49function clip(text: string, n: number): string {
50  const one = text.replace(/\s+/g, ' ').trim()
51  return one.length > n ? one.slice(0, n - 1) + '…' : one
52}
53
54function buildPrompt(idea: string): string {
55  return [
56    `Build a Claude Code mod for this: ${idea}`,
57    'Load the plugin-authoring skill and follow it: write the mod in this session\'s mods folder, then validate, type-check and test it.',
58    'Constraints: zero model tokens at run time wherever possible (no model calls in hooks unless the feature needs one, and then the small fast model);',
59    'never rewrite or trim prompts, system prompt or tool results in a way that could lower answer quality; prefer suggestions over silent actions.',
60    'Check the installed commands first so it does not duplicate an existing mod. Finish with 3 lines: what it does, its commands, its cost.',
61  ].join(' ')
62}
63
64async function registerMacro($: EngineInterface, m: Macro) {
65  await $.command.register({ name: m.name, description: `Macro: ${clip(m.text, 90)}` })
66}
67
68export const register: Register = (on, options) => {
69  const isAutoMacros = options.autoMacros !== false
70  const isAutoFocus = options.autoFocus !== false
71  let isOn = true
72  let macros: Macro[] = []
73  let installed = new Set<string>()
74  const shown = new Set<string>()
75  const recent: string[] = []
76  let lastToast = -Infinity
77  let isFocusDone = false
78
79  function remember(line: string) {
80    recent.push(line)
81    if (recent.length > 10) recent.shift()
82  }
83
84  on('session.start', async ($, e, next) => {
85    await $.command.register({
86      name: 'scout',
87      description: 'mod-scout: suggestions so far, your macros, and /scout build <idea> to have Claude make a new mod',
88      argumentHint: '[build <idea> | macros | rm <macro> | on | off]',
89    })
90    isOn = (await $.store.get('isOn')) !== false
91    const saved = await $.store.get('macros')
92    macros = Array.isArray(saved) ? (saved as Macro[]) : []
93    installed = await commandNames($)
94    for (const m of macros) if (!installed.has(m.name)) await registerMacro($, m).catch(() => undefined)
95
96    return next(e)
97  })
98
99  on('command.run', async ($, e, next) => {
100    const macro = macros.find(m => m.name === e.command)
101    if (macro === undefined) return next(e)
102    const extra = e.args.trim()
103    const text = extra ? `${macro.text}\n\n${extra}` : macro.text
104    $.clock.after(50, () => void $.prompt.submit({ text, asUser: true }))
105
106    return { text: `/${macro.name} sent its prompt.` }
107  }).catch(($, e, next) => next(e))
108
109  on('command.run', { command: 'scout' }, async ($, e) => {
110    const args = e.args.trim()
111    const [word = '', ...rest] = args.split(/\s+/)
112    if (word === 'build' && rest.length > 0) {
113      const idea = rest.join(' ')
114      $.clock.after(50, () => void $.prompt.submit({ text: buildPrompt(idea), asUser: true }))
115      return { text: `Asking Claude to build a mod for: ${idea}` }
116    }
117    if (word === 'on' || word === 'off') {
118      isOn = word === 'on'
119      await $.store.set('isOn', isOn)
120      return { text: `mod-scout ${word}.` }
121    }
122    if (word === 'rm' && rest[0]) {
123      const name = rest[0].replace(/^\//, '')
124      if (!macros.some(m => m.name === name)) return { text: `No macro /${name}.` }
125      macros = macros.filter(m => m.name !== name)
126      await $.store.set('macros', macros)
127      return { text: `Removed /${name}. It disappears from the command list next session.` }
128    }
129    const lines = [
130      `mod-scout is ${isOn ? 'on' : 'off'}.`,
131      `Macros (${macros.length}): ${macros.map(m => `/${m.name}`).join(', ') || 'none yet. Send the same prompt 3 times and one is made.'}`,
132      `Recent suggestions: ${recent.length === 0 ? 'none' : ''}`,
133      ...recent.map(r => `• ${r}`),
134      'Make a new mod: /scout build <what it should do>',
135    ]
136
137    return { text: lines.join('\n') }
138  })
139
140  on('prompt.submit', async ($, e, next) => {
141    if (!isOn || e.command || e.isMeta || !PERSON.has(e.origin.kind)) return next(e)
142    const text = e.text.trim()
143    const now = await $.clock.now()
144    // Other mods register their commands as they start: read the list fresh.
145    installed = new Set([...(await commandNames($)), ...macros.map(m => m.name)])
146
147    // 1. The one rule that fits, if its mod is installed and it was not shown yet.
148    const rule = RULES.find(r => !shown.has(r.id) && installed.has(r.command) && r.test.test(text))
149    let tip: string | undefined = rule?.tip
150    if (rule) shown.add(rule.id)
151    if (!tip && !shown.has('inbox') && installed.has('inbox') && listCount(text) >= 3) {
152      shown.add('inbox')
153      tip = 'Several independent tasks: /inbox each one, then Send, and they run in parallel subagents'
154    }
155    if (tip) {
156      remember(tip)
157      if (now - lastToast > 60_000) {
158        lastToast = now
159        $.ui.toast(`💡 ${tip}`)
160      }
161    }
162
163    // 2. The session's first real task becomes the focus goal, when none is set.
164    if (isAutoFocus && !isFocusDone && installed.has('aim') && TASK.test(text) && text.length >= 30 && text.length <= 600) {
165      isFocusDone = true
166      const goal = clip(text.split(/(?<=[.?!])\s|\n/)[0] ?? text, 70)
167      $.clock.after(50, () => void $.command.run({ command: 'aim', args: `auto ${goal}` }).catch(() => undefined))
168    }
169
170    // 3. A prompt sent for the third time becomes a slash command.
171    if (isAutoMacros && text.length >= 15 && text.length <= 1500) {
172      const key = normalize(text)
173      const counts = ((await $.store.get('counts')) ?? {}) as Record<string, Count>
174      const seen = counts[key]
175      counts[key] = { n: (seen?.n ?? 0) + 1, text, at: now }
176      const keys = Object.keys(counts)
177      if (keys.length > 300) {
178        keys.sort((a, b) => (counts[a]?.at ?? 0) - (counts[b]?.at ?? 0))
179        for (const old of keys.slice(0, keys.length - 300)) delete counts[old]
180      }
181      await $.store.set('counts', counts)
182      if (counts[key]?.n === 3 && !macros.some(m => normalize(m.text) === key)) {
183        const taken = new Set([...installed, ...macros.map(m => m.name)])
184        const macro: Macro = { name: slugOf(text, taken), text, createdAt: now }
185        macros = [...macros, macro]
186        await $.store.set('macros', macros)
187        installed.add(macro.name)
188        $.clock.after(50, () => void registerMacro($, macro).catch(() => undefined))
189        remember(`Made /${macro.name} for a prompt you sent 3 times`)
190        $.ui.toast(`⚡ You sent this 3 times: /${macro.name} now sends it. /scout rm ${macro.name} undoes it.`)
191      }
192    }
193
194    return next(e)
195  }).catch(($, e, next) => next(e))
196}
197