command-hub

1import { atom, read, update } from 'claude-code'
2import type { ElementTable, EngineInterface, Register, RenderChildren } from 'claude-code'
3
4import type { CommandDraft, CommandRow } from '../types'
5
6// ── claude-mods kit v1 (docs/design.md): identical in every mod ──
7const TONE = { accent: 'claude', ok: 'success', warn: 'warning', bad: 'error', dim: 'inactive' } as const
8const GLYPH = { on: '●', off: '○', warn: '▲', ok: '✓', fail: '✗' } as const
9type Kit = Pick<ElementTable, 'Box' | 'Text'>
10
11/** Pane header: state glyph, mod name, one-line live status. */
12function header({ Box, Text }: Kit, glyph: string, tone: string, name: string, status: string) {
13  return (
14    <Box gap={1}>
15      <Text color={tone}>{glyph}</Text>
16      <Text bold>{name}</Text>
17      <Text dimColor wrap="truncate-end">{status}</Text>
18    </Box>
19  )
20}
21
22/** A section: a dim label (with optional small controls beside it), then its rows. */
23function section({ Box, Text }: Kit, label: string, rows: RenderChildren, aside?: RenderChildren) {
24  return (
25    <Box flexDirection="column">
26      <Box gap={1}>
27        <Text dimColor>{label}</Text>
28        {aside}
29      </Box>
30      {rows}
31    </Box>
32  )
33}
34
35/** A number right-aligned in a fixed-width cell. */
36function num({ Box, Text }: Kit, value: string, width: number, color?: string) {
37  return (
38    <Box width={width} flexShrink={0} justifyContent="flex-end">
39      <Text color={color}>{value}</Text>
40    </Box>
41  )
42}
43
44/** Empty state: what will show up here, and how to get it. */
45function empty({ Text }: Kit, text: string) {
46  return <Text dimColor>{text}</Text>
47}
48// ── end kit ──
49
50const PANE = 'command-hub'
51const commands = atom({ plugin: 'command-hub', key: 'commands' } as const, [])
52const query = atom({ plugin: 'command-hub', key: 'query' } as const, '')
53const tab = atom({ plugin: 'command-hub', key: 'tab' } as const, 'essentials' as 'essentials' | 'all' | 'create')
54const draft = atom({ plugin: 'command-hub', key: 'draft' } as const, { name: '', description: '', body: '', scope: 'project' } as CommandDraft)
55
56/** The built-in commands people most often don't know about, and when to reach for them. Shown only if present. */
57const ESSENTIALS: { name: string; when: string }[] = [
58  { name: 'compact', when: 'Context getting full? Summarizes the chat to free space. Add text to say what to keep: /compact keep the API design' },
59  { name: 'clear', when: 'Switching to an unrelated task: fresh context, same window. Cheaper and sharper than one endless chat.' },
60  { name: 'context', when: 'See exactly what is eating your context window (files, MCP tools, messages).' },
61  { name: 'rewind', when: 'Undo: roll code and/or conversation back to an earlier message (also Esc Esc).' },
62  { name: 'resume', when: 'Reopen an earlier session with its full history.' },
63  { name: 'btw', when: 'Ask a quick side question without derailing the main task.' },
64  { name: 'init', when: 'New project? Generates CLAUDE.md so Claude knows your build/test commands and conventions.' },
65  { name: 'memory', when: 'Edit the CLAUDE.md files loaded every session: put "always do X" rules here.' },
66  { name: 'model', when: 'Switch model: bigger for hard design/debugging, smaller for quick edits.' },
67  { name: 'effort', when: 'Trade speed for depth of thinking.' },
68  { name: 'plan', when: 'Make Claude propose a plan before touching code.' },
69  { name: 'permissions', when: 'Tired of approving the same command? Allow-list it (or deny things forever).' },
70  { name: 'add-dir', when: 'Let Claude work in another folder too (e.g. a shared library repo).' },
71  { name: 'agents', when: 'Create specialised subagents (reviewer, tester…) with their own prompts and tools.' },
72  { name: 'mcp', when: 'Connect or debug MCP servers (databases, browsers, issue trackers…).' },
73  { name: 'hooks', when: 'Run your own scripts automatically: format after edit, block commands, notify…' },
74  { name: 'review', when: 'Have Claude review a pull request or your local changes.' },
75  { name: 'code-review', when: 'Review the current diff for bugs at an effort level you choose.' },
76  { name: 'security-review', when: 'Security pass over your pending changes.' },
77  { name: 'export', when: 'Save the conversation to a file or the clipboard.' },
78  { name: 'usage', when: 'Your plan limits and when they reset.' },
79  { name: 'plugin', when: 'Browse and install plugins and mod collections like this one.' },
80  { name: 'statusline', when: 'Customise the line under the prompt (branch, cost, context…).' },
81  { name: 'doctor', when: 'Something broken? Diagnoses your install and settings.' },
82]
83
84/** Phrases in a prompt that mean a built-in command would do the job better. */
85const HINTS: { re: RegExp; name: string; tip: string }[] = [
86  { re: /\b(undo|revert|go back|roll ?back)\b/i, name: 'rewind', tip: '/rewind (or Esc Esc) restores code and chat to an earlier point.' },
87  { re: /\b(remember|from now on|always (use|do)|every time)\b/i, name: 'memory', tip: 'For rules that should stick across sessions, put them in CLAUDE.md via /memory.' },
88  { re: /\b(new task|unrelated|different (topic|thing)|start over)\b/i, name: 'clear', tip: 'Switching topics? /clear gives a fresh, cheaper context.' },
89  { re: /\b(yesterday|last session|previous session|earlier session)\b/i, name: 'resume', tip: '/resume reopens an earlier session with its full history.' },
90  { re: /\b(another|other|second) (folder|directory|repo)\b/i, name: 'add-dir', tip: '/add-dir gives Claude access to another folder.' },
91  { re: /\b(stop asking|keeps asking|approve every)\b/i, name: 'permissions', tip: '/permissions lets you allow-list commands you trust.' },
92  { re: /\bsecurity\b|\bvulnerab/i, name: 'security-review', tip: '/security-review runs a dedicated security pass on your changes.' },
93  { re: /\breview (my|the|this) (pr|pull request|changes|diff|code)\b/i, name: 'review', tip: '/review is built for exactly this.' },
94]
95
96const NAME_OK = /^[a-z0-9][a-z0-9-]{0,40}$/
97
98async function loadCommands($: EngineInterface) {
99  const list = await $.command.list()
100  await update($, commands, () => list.map(c => ({ name: c.name, description: c.description, source: c.plugin ? `plugin: ${c.plugin}` : c.source })))
101}
102
103async function saveDraft($: EngineInterface) {
104  const d = await read($, draft)
105  const name = d.name.trim().replace(/^\//, '')
106  if (!NAME_OK.test(name)) {
107    $.ui.toast('Name: lowercase letters, digits and dashes only.')
108    return
109  }
110  if (d.body.trim() === '') {
111    $.ui.toast('Write what the command should tell Claude to do.')
112    return
113  }
114  if ((await read($, commands)).some(c => c.name === name)) {
115    $.ui.toast(`/${name} already exists; pick another name.`)
116    return
117  }
118  const home = (await $.env.get('HOME')) ?? (await $.env.get('USERPROFILE')) ?? ''
119  const dir = d.scope === 'user' ? `${home}/.claude/commands` : `${await $.session.root()}/.claude/commands`
120  const path = `${dir}/${name}.md`.replace(/\\/g, '/')
121  if (await $.fs.exists(path)) {
122    $.ui.toast(`${path} exists already.`)
123    return
124  }
125  const hasArgs = d.body.includes('$ARGUMENTS')
126  const front = [`description: ${d.description.trim() || name}`, ...(hasArgs ? ['argument-hint: <details>'] : [])].join('\n')
127  await $.fs.write(path, `---\n${front}\n---\n\n${d.body.trim()}\n`)
128  await update($, draft, (): CommandDraft => ({ name: '', description: '', body: '', scope: d.scope }))
129  $.ui.toast(`Saved /${name} → ${path}. It shows in the / menu (restart if it doesn't yet).`, { timeoutMs: 9000 })
130}
131
132async function open($: EngineInterface, view: 'essentials' | 'all' | 'create') {
133  await loadCommands($)
134  await update($, tab, () => view)
135  await $.ui.open({ id: PANE, title: 'Commands' })
136}
137
138export const register: Register = on => {
139  const tipped = new Set<string>()
140
141  on('session.start', async ($, e, next) => {
142    await $.command.register({ name: 'cmds', description: 'Command hub: discover, search and create slash commands' })
143    await $.command.register({ name: 'new-command', description: 'Create your own slash command (opens the form)' })
144    void loadCommands($)
145
146    return next(e)
147  })
148
149  on('command.run', { command: 'cmds' }, async $ => {
150    await open($, 'essentials')
151
152    return { text: 'Command hub opened.' }
153  })
154
155  on('command.run', { command: 'new-command' }, async $ => {
156    await open($, 'create')
157
158    return { text: 'Command creator opened.' }
159  })
160
161  on('prompt.submit', async ($, e, next) => {
162    const available = new Set((await read($, commands)).map(c => c.name))
163    for (const hint of HINTS) {
164      if (!tipped.has(hint.name) && available.has(hint.name) && hint.re.test(e.text)) {
165        tipped.add(hint.name)
166        $.ui.toast(`Tip: ${hint.tip}`, { timeoutMs: 9000 })
167        break
168      }
169    }
170
171    return next(e)
172  })
173
174  on('ui.render', { component: 'Pane', requestId: PANE }, async ($, e) => {
175    const els = $.ui.resolve(e)
176    const { Box, Text, Button } = els
177    const Input = 'Input' in els ? els.Input : undefined
178    const Select = 'Select' in els ? els.Select : undefined
179    const list = await read($, commands)
180    const view = await read($, tab)
181    const q = (await read($, query)).toLowerCase()
182    const d = await read($, draft)
183    const names = new Set(list.map(c => c.name))
184    const use = (name: string) => () => void $.prompt.fill({ text: `/${name} ` })
185    const kit = { Box, Text }
186    const top = header(kit, GLYPH.on, TONE.accent, 'command-hub', list.length === 0 ? 'reading commands…' : `${list.length} commands installed`)
187
188    const tabs = (
189      <Box gap={1}>
190        {(['essentials', 'all', 'create'] as const).map((v, i) => (
191          <Button key={`tab-${v}`} hotkey={String(i + 1)} variant={view === v ? 'primary' : 'secondary'} label={v === 'create' ? '+ create' : v} onPress={() => void update($, tab, () => v)} />
192        ))}
193      </Box>
194    )
195
196    if (view === 'essentials') {
197      const shown = ESSENTIALS.filter(x => names.has(x.name))
198
199      return (
200        <Box flexDirection="column" gap={1}>
201          {top}
202          {tabs}
203          {section(
204            kit,
205            'Built-ins worth knowing · click one to put it in the prompt box',
206            <Box flexDirection="column">
207              {shown.length === 0 && empty(kit, 'Reading the commands this Claude Code has… they appear here in a moment.')}
208              {shown.map(x => (
209                <Box flexDirection="column">
210                  <Button key={`use-${x.name}`} plain label={`/${x.name}`} onPress={use(x.name)} />
211                  <Box paddingLeft={3}>
212                    <Text dimColor>{x.when}</Text>
213                  </Box>
214                </Box>
215              ))}
216            </Box>,
217          )}
218        </Box>
219      )
220    }
221
222    if (view === 'all') {
223      const filtered = list.filter(c => q === '' || c.name.toLowerCase().includes(q) || c.description.toLowerCase().includes(q))
224      const bySource = new Map<string, CommandRow[]>()
225      for (const c of filtered) bySource.set(c.source, [...(bySource.get(c.source) ?? []), c])
226
227      return (
228        <Box flexDirection="column" gap={1}>
229          {top}
230          {tabs}
231          {Input !== undefined && <Input key="search" placeholder="search commands…" value={q} onInput={(v: string) => void update($, query, () => v)} onSubmit={(v: string) => void update($, query, () => v)} />}
232          <Text dimColor>
233            {filtered.length} of {list.length} commands
234          </Text>
235          {filtered.length === 0 && empty(kit, q === '' ? 'Reading the installed commands… they appear here in a moment.' : `No command matches "${q}". Try a shorter word, or clear the search.`)}
236          {[...bySource.entries()].map(([source, rows]) =>
237            section(
238              kit,
239              source,
240              rows.map(c => (
241                <Box gap={1}>
242                  <Button key={`all-${c.name}`} plain label={`/${c.name}`} onPress={use(c.name)} />
243                  <Text dimColor wrap="truncate-end">
244                    {c.description}
245                  </Text>
246                </Box>
247              )),
248            ),
249          )}
250        </Box>
251      )
252    }
253
254    return (
255      <Box flexDirection="column" gap={1}>
256        {top}
257        {tabs}
258        <Text dimColor>A slash command is a saved prompt. Use $ARGUMENTS where text typed after the command should go.</Text>
259        {Input === undefined ? (
260          <Text>This surface has no text input; use /new-command in the terminal or desktop app.</Text>
261        ) : (
262          <Box flexDirection="column" gap={1}>
263            <Input key="name" label="Name  /" placeholder="e.g. ship" value={d.name} onInput={(v: string) => void update($, draft, x => ({ ...x, name: v }))} onSubmit={(v: string) => void update($, draft, x => ({ ...x, name: v }))} />
264            <Input key="desc" label="Shown in menu" placeholder="e.g. Run tests, then commit and push" value={d.description} onInput={(v: string) => void update($, draft, x => ({ ...x, description: v }))} onSubmit={(v: string) => void update($, draft, x => ({ ...x, description: v }))} />
265            <Input
266              key="body"
267              label="Prompt"
268              placeholder="e.g. Run the test suite. If green, commit with a good message and push. Focus: $ARGUMENTS"
269              value={d.body}
270              onInput={(v: string) => void update($, draft, x => ({ ...x, body: v }))}
271              onSubmit={(v: string) => void update($, draft, x => ({ ...x, body: v }))}
272            />
273            {Select !== undefined && (
274              <Select
275                key="scope"
276                label="Save for"
277                value={d.scope}
278                options={[
279                  { value: 'project', label: 'This project (.claude/commands, shareable via git)' },
280                  { value: 'user', label: 'Me, everywhere (~/.claude/commands)' },
281                ]}
282                onSelect={(v: string) => void update($, draft, (x): CommandDraft => ({ ...x, scope: v === 'user' ? 'user' : 'project' }))}
283              />
284            )}
285            <Box gap={1}>
286              <Button key="save" variant="primary" label="Save command" onPress={() => void saveDraft($)} />
287              <Button
288                key="help"
289                label="Draft it with Claude"
290                onPress={() => void $.prompt.fill({ text: `Help me write a Claude Code slash command (a markdown file in .claude/commands) that ${d.description || d.body || '…'}. Ask me anything you need, then create it.` })}
291              />
292            </Box>
293          </Box>
294        )}
295      </Box>
296    )
297  })
298}
299

1export type CommandRow = { name: string; description: string; source: string }
2
3export type CommandDraft = { name: string; description: string; body: string; scope: 'project' | 'user' }
4
5declare module 'claude-code' {
6  interface PluginState {
7    'command-hub': {
8      commands: CommandRow[]
9      query: string
10      tab: 'essentials' | 'all' | 'create'
11      draft: CommandDraft
12    }
13  }
14}
15