toolbox

1import { atom, read, update } from 'claude-code'
2import type { ElementTable, EngineInterface, Register, RenderChildren } from 'claude-code'
3
4import type { Suggestion, ToolRow } 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 = 'toolbox'
51const tools = atom({ plugin: 'toolbox', key: 'tools' } as const, [])
52const counts = atom({ plugin: 'toolbox', key: 'counts' } as const, {} as Record<string, number>)
53const suggestions = atom({ plugin: 'toolbox', key: 'suggestions' } as const, [])
54const stack = atom({ plugin: 'toolbox', key: 'stack' } as const, [])
55const filter = atom({ plugin: 'toolbox', key: 'filter' } as const, 'all')
56
57/** Plain-language explanations of the built-in tools, for people new to Claude Code. */
58const EXPLAIN: Record<string, string> = {
59  Bash: 'Runs shell commands (builds, tests, git…)',
60  PowerShell: 'Runs PowerShell commands on Windows',
61  Read: 'Reads files, images, PDFs and notebooks',
62  Write: 'Creates or overwrites a file',
63  Edit: 'Makes exact find-and-replace edits in a file',
64  NotebookEdit: 'Edits Jupyter notebook cells',
65  Glob: 'Finds files by name pattern',
66  Grep: 'Searches file contents (ripgrep)',
67  WebFetch: 'Downloads and reads a web page',
68  WebSearch: 'Searches the web',
69  Agent: 'Starts a subagent for a side task (keeps main context clean)',
70  Task: 'Starts a subagent for a side task (keeps main context clean)',
71  TodoWrite: 'Keeps a visible todo plan for multi-step work',
72  AskUserQuestion: 'Asks you a multiple-choice question',
73  Skill: 'Loads a packaged skill (instructions for a kind of task)',
74  ToolSearch: 'Loads the schemas of deferred tools on demand',
75  EnterPlanMode: 'Switches to plan-first mode',
76  ExitPlanMode: 'Presents a plan for your approval',
77  Monitor: 'Watches a background process for a condition',
78}
79
80const firstSentence = (s: string) => {
81  const line = s.split('\n').find(l => l.trim() !== '')?.trim() ?? ''
82  const cut = line.split(/(?<=\.)\s/)[0] ?? line
83
84  return cut.length > 90 ? `${cut.slice(0, 89)}…` : cut
85}
86
87async function loadTools($: EngineInterface) {
88  const list = await $.tool.list()
89  const rows: ToolRow[] = list.map(t => {
90    const mcp = /^mcp__(.+?)__(.+)$/.exec(t.name)
91    const server = mcp?.[1] ?? ''
92
93    return {
94      name: t.name,
95      group: t.mcp || mcp ? `MCP: ${/^[0-9a-f-]{20,}$/.test(server) ? 'connector' : server}` : 'Built-in',
96      short: EXPLAIN[t.name] ?? firstSentence(t.description),
97      isMcp: t.mcp,
98    }
99  })
100  await update($, tools, () => rows)
101}
102
103async function exists($: EngineInterface, root: string, rel: string) {
104  return $.fs.exists(`${root}/${rel}`).catch(() => false)
105}
106
107/** Looks at the project folder and proposes tools, MCP servers and habits that fit it. */
108async function scan($: EngineInterface) {
109  const root = (await $.session.root()).replace(/\\/g, '/')
110  const has = (rel: string) => exists($, root, rel)
111  const found: string[] = []
112  const out: Suggestion[] = []
113  const toolNames = (await read($, tools)).map(t => t.name.toLowerCase()).join(' ')
114
115  let deps: Record<string, unknown> = {}
116  let scripts: Record<string, unknown> = {}
117  if (await has('package.json')) {
118    found.push('Node')
119    try {
120      const pkg = JSON.parse(await $.fs.read(`${root}/package.json`)) as { dependencies?: Record<string, unknown>; devDependencies?: Record<string, unknown>; scripts?: Record<string, unknown> }
121      deps = { ...pkg.dependencies, ...pkg.devDependencies }
122      scripts = pkg.scripts ?? {}
123    } catch {
124      // unreadable package.json
125    }
126  }
127  const dep = (name: string) => Object.keys(deps).some(d => d === name || d.startsWith(`${name}/`) || d.startsWith(`@${name}/`))
128
129  if (dep('react') || dep('next') || dep('vue') || dep('svelte') || dep('vite') || dep('@angular/core')) found.push('Web UI')
130  if (dep('typescript')) found.push('TypeScript')
131  if ((await has('pyproject.toml')) || (await has('requirements.txt'))) found.push('Python')
132  if (await has('Cargo.toml')) found.push('Rust')
133  if (await has('go.mod')) found.push('Go')
134  if ((await has('Dockerfile')) || (await has('docker-compose.yml')) || (await has('compose.yaml'))) found.push('Docker')
135  if (dep('prisma') || dep('drizzle-orm') || dep('pg') || dep('mongoose') || (await has('prisma/schema.prisma'))) found.push('Database')
136  if (await has('.github/workflows')) found.push('GitHub Actions')
137  const isGit = await has('.git')
138  if (isGit) found.push('git')
139
140  if (!(await has('CLAUDE.md')) && !(await has('.claude/CLAUDE.md'))) {
141    out.push({ id: 'init', title: 'Give Claude a project memory', why: 'No CLAUDE.md here. /init writes one with your build/test commands and conventions, so you stop repeating them.', action: { kind: 'command', value: 'init', label: 'Run /init' } })
142  }
143  if (found.includes('Web UI') && !/browser|playwright|puppeteer|chrome/.test(toolNames)) {
144    out.push({ id: 'browser', title: 'Let Claude see your UI', why: 'Web frontend detected but no browser tool. A browser/Playwright MCP lets Claude click through the app and check its own changes.', action: { kind: 'fill', value: 'Help me set up a browser automation MCP server (e.g. Playwright) for this project so you can check UI changes yourself.', label: 'Ask Claude to set it up' } })
145  }
146  if (found.includes('Database') && !/postgres|sql|supabase|mongo|prisma|neon/.test(toolNames)) {
147    out.push({ id: 'db', title: 'Database access for Claude', why: 'An ORM/DB driver is in this project. A read-only database MCP lets Claude check the real schema and data instead of guessing.', action: { kind: 'fill', value: 'Which database MCP server fits this project? Set up a read-only connection for local development.', label: 'Ask Claude' } })
148  }
149  if (isGit) {
150    const gh = await $.process.run(['gh', '--version']).catch(() => undefined)
151    if (gh === undefined || gh.exitCode !== 0) {
152      out.push({ id: 'gh', title: 'Install the GitHub CLI', why: 'With `gh` Claude can open PRs, read issues and check CI from the terminal.' })
153    }
154  }
155  const testScript = Object.keys(scripts).find(s => /^test/.test(s))
156  if (testScript !== undefined || (await has('pytest.ini')) || (await has('Cargo.toml')) || (await has('go.mod'))) {
157    out.push({ id: 'verify', title: 'Make Claude verify its work', why: 'Tests exist. Telling Claude how to verify (in CLAUDE.md) catches mistakes before you see them.', action: { kind: 'fill', value: `Add a "How to verify changes" section to CLAUDE.md with the exact test${testScript ? ` (npm run ${testScript})` : ''}, lint and type-check commands for this project.`, label: 'Add to CLAUDE.md' } })
158  }
159  if (!(await has('.claude/settings.json'))) {
160    out.push({ id: 'perms', title: 'Fewer permission prompts', why: 'No project settings yet. Allow-listing safe read-only commands (git status, tests) saves a lot of clicking.', action: { kind: 'command', value: 'fewer-permission-prompts', label: 'Scan & suggest' } })
161  }
162  out.push({ id: 'ask', title: 'Ask Claude for a tailored tool review', why: 'Claude reads this project and the tool list above and tells you what is missing or unused.', action: { kind: 'submit', value: 'Look at this project (stack, scripts, CI) and at the tools, MCP servers and skills you currently have. Suggest the 3 most useful additions for this project and anything I have that is unused noise. Be concrete, no setup yet.', label: 'Ask now' } })
163
164  await update($, stack, () => found)
165  await update($, suggestions, () => out)
166}
167
168async function act($: EngineInterface, s: Suggestion) {
169  const action = s.action
170  if (action === undefined) return
171  if (action.kind === 'command') {
172    const available = (await $.command.list()).some(c => c.name === action.value)
173    if (!available) {
174      $.ui.toast(`/${action.value} is not available in this session.`)
175      return
176    }
177    await $.command.run({ command: action.value })
178  } else if (action.kind === 'fill') {
179    await $.prompt.fill({ text: action.value })
180  } else {
181    await $.prompt.submit({ text: action.value })
182  }
183}
184
185export const register: Register = on => {
186  on('session.start', async ($, e, next) => {
187    await $.command.register({ name: 'tools', description: 'See every tool Claude can use, how often it used them, and suggestions for this project' })
188    void loadTools($)
189
190    return next(e)
191  })
192
193  on('command.run', { command: 'tools' }, async $ => {
194    await loadTools($)
195    void scan($)
196    await $.ui.open({ id: PANE, title: 'Tools' })
197
198    return { text: 'Tools panel opened.' }
199  })
200
201  on('tool.call', async ($, e, next) => {
202    await update($, counts, c => ({ ...c, [e.tool]: (c[e.tool] ?? 0) + 1 }))
203
204    return next(e)
205  })
206
207  on('ui.render', { component: 'Pane', requestId: PANE }, async ($, e) => {
208    const { Box, Text, Button } = $.ui.resolve(e)
209    const rows = await read($, tools)
210    const used = await read($, counts)
211    const tips = await read($, suggestions)
212    const found = await read($, stack)
213    const view = await read($, filter)
214
215    const groups = new Map<string, ToolRow[]>()
216    for (const row of rows) {
217      if (view === 'used' && (used[row.name] ?? 0) === 0) continue
218      if (view === 'mcp' && !row.isMcp) continue
219      groups.set(row.group, [...(groups.get(row.group) ?? []), row])
220    }
221    const shortName = (n: string) => n.replace(/^mcp__.+?__/, '')
222
223    const kit = { Box, Text }
224    const usedCount = Object.keys(used).length
225    const shown = [...groups.values()].reduce((n, list) => n + list.length, 0)
226
227    return (
228      <Box flexDirection="column" gap={1}>
229        {header(kit, GLYPH.on, TONE.accent, 'toolbox', rows.length === 0 ? 'reading tools…' : `${rows.length} tools · ${usedCount} used this session`)}
230
231        {section(
232          kit,
233          `For this project${found.length > 0 ? ` (${found.join(', ')})` : ''}`,
234          <Box flexDirection="column">
235            {tips.length === 0 && empty(kit, 'Looking at this project… suggestions appear here in a moment.')}
236            {tips.map(s => (
237              <Box flexDirection="column">
238                <Box gap={1}>
239                  <Text color={TONE.accent}>{GLYPH.on}</Text>
240                  <Text wrap="truncate-end">{s.title}</Text>
241                  {s.action !== undefined && <Button key={`act-${s.id}`} plain label={s.action.label} onPress={() => void act($, s)} />}
242                </Box>
243                <Box paddingLeft={2}>
244                  <Text dimColor>{s.why}</Text>
245                </Box>
246              </Box>
247            ))}
248          </Box>,
249        )}
250
251        {section(
252          kit,
253          'Tools',
254          <Box flexDirection="column" gap={1}>
255            {shown === 0 && empty(kit, view === 'used' ? 'No tools used yet this session. Counts go up as Claude works.' : view === 'mcp' ? 'No MCP tools connected. /mcp adds servers (databases, browsers, issue trackers…).' : 'Reading the tool list…')}
256            {[...groups.entries()].map(([group, list]) =>
257              section(
258                kit,
259                `${group} (${list.length})`,
260                list.map(t => (
261                  <Box gap={1}>
262                    {(used[t.name] ?? 0) > 0 ? num(kit, `${used[t.name]}×`, 5) : num(kit, '·', 5, TONE.dim)}
263                    <Text wrap="truncate-end">
264                      {shortName(t.name)} <Text dimColor>{t.short}</Text>
265                    </Text>
266                  </Box>
267                )),
268              ),
269            )}
270          </Box>,
271          <Box gap={1}>
272            {(['all', 'used', 'mcp'] as const).map((v, i) => (
273              <Button key={`f-${v}`} plain hotkey={String(i + 1)} label={view === v ? `[${v}]` : v} onPress={() => void update($, filter, () => v)} />
274            ))}
275          </Box>,
276        )}
277        <Box>
278          <Button key="rescan" hotkey="r" variant="primary" label="Rescan" onPress={() => void loadTools($).then(() => scan($))} />
279        </Box>
280      </Box>
281    )
282  })
283}
284

1export type ToolRow = { name: string; group: string; short: string; isMcp: boolean }
2
3export type Suggestion = { id: string; title: string; why: string; action?: { kind: 'command' | 'fill' | 'submit'; value: string; label: string } }
4
5declare module 'claude-code' {
6  interface PluginState {
7    toolbox: {
8      tools: ToolRow[]
9      counts: Record<string, number>
10      suggestions: Suggestion[]
11      stack: string[]
12      filter: string
13    }
14  }
15}
16