mod-manager

1import { atom, read, update } from 'claude-code'
2import type { ElementTable, EngineInterface, Register, RenderChildren } from 'claude-code'
3
4import type { ModRow, ModStatus } 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 = 'mod-manager'
51const MARKETPLACE = 'claude-mods'
52const rows = atom({ plugin: 'mod-manager', key: 'rows' } as const, [])
53const busy = atom({ plugin: 'mod-manager', key: 'busy' } as const, null)
54const message = atom({ plugin: 'mod-manager', key: 'message' } as const, '')
55const needsRestart = atom({ plugin: 'mod-manager', key: 'needsRestart' } as const, false)
56const self = atom({ plugin: 'mod-manager', key: 'self' } as const, null as ModRow | null)
57
58/** The mods this manager knows how to describe; anything else in the marketplace is listed with its own description. */
59const CATALOG: { name: string; blurb: string; usesTokens: boolean }[] = [
60  { name: 'guardrails', blurb: 'Safety rules and presets: block rm -rf, mass deletes, force-push, secrets, installs, network; or lock Claude to the project.', usesTokens: false },
61  { name: 'activity', blurb: 'Live panel: what Claude is running right now and what it is waiting on.', usesTokens: false },
62  { name: 'notify', blurb: 'OS notifications when a long task finishes or an approval is waiting.', usesTokens: false },
63  { name: 'context-keeper', blurb: 'What fills your context window, plus checkpoints that survive /compact.', usesTokens: true },
64  { name: 'usage-meter', blurb: '5h/7d plan limits with burn rate and cache hit ratio.', usesTokens: false },
65  { name: 'prompt-coach', blurb: 'Suggests a sharper prompt before sending; you choose which one goes.', usesTokens: true },
66  { name: 'command-hub', blurb: 'The built-in slash commands explained, plus a form to make your own.', usesTokens: false },
67  { name: 'toolbox', blurb: 'Every tool Claude can use, how often it used them, and tips for this project.', usesTokens: false },
68  { name: 'changes', blurb: 'Files Claude changed this session with +/- counts, and one-click why, summary or self-review.', usesTokens: false },
69  { name: 'loop-breaker', blurb: 'Notices Claude going in circles (same failing command, same file patched again) and nudges it to rethink.', usesTokens: false },
70  { name: 'quickbar', blurb: 'A one-line launcher above the prompt: live context % and buttons for every claude-mods panel.', usesTokens: false },
71]
72
73const PRESETS: { id: string; label: string; mods: string[] }[] = [
74  { id: 'safety', label: 'Safety only', mods: ['guardrails', 'notify'] },
75  { id: 'essentials', label: 'Essentials', mods: ['guardrails', 'activity', 'notify', 'context-keeper', 'usage-meter'] },
76  { id: 'zero', label: 'Zero tokens', mods: CATALOG.filter(m => !m.usesTokens).map(m => m.name) },
77  { id: 'all', label: 'Everything', mods: CATALOG.map(m => m.name) },
78]
79
80let cliPath = 'claude'
81
82type Action = 'install' | 'enable' | 'disable' | 'uninstall' | 'update'
83
84type Listing = {
85  installed?: { id: string; version?: string; scope?: string; enabled?: boolean; projectPath?: string }[]
86  available?: { name: string; description?: string; marketplaceName?: string }[]
87}
88
89/** Runs `claude plugin …`; through cmd on Windows so an npm-installed claude.cmd resolves too. */
90async function cli($: EngineInterface, args: string[], timeoutMs = 120000, cwd?: string) {
91  const argv = (await $.env.get('OS')) === 'Windows_NT' ? ['cmd', '/d', '/c', cliPath, ...args] : [cliPath, ...args]
92
93  return $.process.run(argv, cwd === undefined ? { timeoutMs } : { timeoutMs, cwd })
94}
95
96const normPath = (path: string) => path.replace(/[\\/]+/g, '/').replace(/\/$/, '').toLowerCase()
97
98/** True when `dir` is `root` or inside it. */
99const isWithin = (dir: string, root: string) => {
100  const d = normPath(dir)
101  const r = normPath(root)
102
103  return d === r || d.startsWith(`${r}/`)
104}
105
106/** True when version `a` is newer than `b` (dotted numbers; anything else compares as 0). */
107const isNewer = (a: string, b: string) => {
108  const pa = a.split('.').map(n => Number.parseInt(n, 10) || 0)
109  const pb = b.split('.').map(n => Number.parseInt(n, 10) || 0)
110  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
111    const d = (pa[i] ?? 0) - (pb[i] ?? 0)
112    if (d !== 0) return d > 0
113  }
114
115  return false
116}
117
118/**
119 * The version each mod has in the marketplace, read from the marketplace's local copy, which is what
120 * `claude plugin update` installs. (`plugin list --available` lists only mods that aren't installed.)
121 */
122async function marketplaceVersions($: EngineInterface) {
123  const versions = new Map<string, string>()
124  try {
125    const isWindows = (await $.env.get('OS')) === 'Windows_NT'
126    const home = (isWindows ? await $.env.get('USERPROFILE') : undefined) ?? (await $.env.get('HOME')) ?? ''
127    const configDir = (await $.env.get('CLAUDE_CONFIG_DIR')) ?? `${home}/.claude`
128    const known = JSON.parse(await $.fs.read(`${configDir}/plugins/known_marketplaces.json`)) as Record<string, { installLocation?: string }>
129    const location = known[MARKETPLACE]?.installLocation
130    if (location === undefined) return versions
131    const manifest = JSON.parse(await $.fs.read(`${location}/.claude-plugin/marketplace.json`)) as { plugins?: { name: string; source?: unknown; version?: string }[] }
132    for (const entry of manifest.plugins ?? []) {
133      if (typeof entry.version === 'string') {
134        versions.set(entry.name, entry.version)
135        continue
136      }
137      if (typeof entry.source !== 'string') continue
138      const plugin = JSON.parse(await $.fs.read(`${location}/${entry.source}/.claude-plugin/plugin.json`).catch(() => '{}')) as { version?: unknown }
139      if (typeof plugin.version === 'string') versions.set(entry.name, plugin.version)
140    }
141  } catch (error) {
142    $.ui.log(`mod-manager: could not read marketplace versions: ${String(error)}`, { to: 'debug' })
143  }
144
145  return versions
146}
147
148async function readListing($: EngineInterface, cwd?: string) {
149  const result = await cli($, ['plugin', 'list', '--available', '--json'], 60000, cwd)
150  if (result.exitCode !== 0) throw new Error(result.stderr.trim() || `exit ${result.exitCode}`)
151
152  return JSON.parse(result.stdout) as Listing
153}
154
155/** Reads what is installed and what the marketplace offers, and merges it with the catalog. */
156async function refresh($: EngineInterface) {
157  let listing: Listing
158  // Local and project installs belong to the folder they were made in, and the CLI only sees them
159  // from there. A session in a subfolder asks from the project folder instead.
160  let root: string | undefined
161  try {
162    const here = await $.session.cwd()
163    listing = await readListing($)
164    root = (listing.installed ?? [])
165      .map(p => p.projectPath)
166      .filter((path): path is string => path !== undefined && path !== '' && isWithin(here, path))
167      .sort((a, b) => b.length - a.length)[0]
168    if (root !== undefined && normPath(root) !== normPath(here)) listing = await readListing($, root)
169  } catch (error) {
170    await update($, message, () => `Couldn't run "${cliPath} plugin list" (${String(error).slice(0, 160)}). Set the Claude Code command in /config if claude isn't on your PATH.`)
171    return
172  }
173
174  const mine = (listing.installed ?? []).filter(p => p.id.endsWith(`@${MARKETPLACE}`))
175  // Another project's local install is not this session's; leave it out.
176  const visible = mine.filter(p => p.projectPath === undefined || p.projectPath === '' || (root !== undefined && normPath(p.projectPath) === normPath(root)))
177  const installed = new Map(visible.map(p => [p.id.split('@')[0] ?? '', p]))
178  const offered = new Map((listing.available ?? []).filter(p => p.marketplaceName === MARKETPLACE).map(p => [p.name, p]))
179  if (installed.size === 0 && offered.size === 0) {
180    await update($, message, () => `The ${MARKETPLACE} marketplace isn't added yet. Run: ${cliPath} plugin marketplace add mishgoldenberg/claude-mods`)
181  }
182
183  const latest = await marketplaceVersions($)
184  const newer = (name: string, version: string | undefined) => {
185    const v = latest.get(name)
186
187    return v !== undefined && version !== undefined && isNewer(v, version) ? v : undefined
188  }
189  const manager = installed.get('mod-manager')
190  await update($, self, (): ModRow | null =>
191    manager === undefined
192      ? null
193      : { name: 'mod-manager', blurb: '', usesTokens: false, status: manager.enabled === false ? 'off' : 'on', version: manager.version, latest: newer('mod-manager', manager.version), scope: manager.scope, projectPath: manager.projectPath || undefined },
194  )
195
196  const known = new Set(CATALOG.map(m => m.name))
197  const extra = [...new Set([...installed.keys(), ...offered.keys()])].filter(n => n !== 'mod-manager' && !known.has(n))
198  const next: ModRow[] = [
199    ...CATALOG,
200    ...extra.map(name => ({ name, blurb: offered.get(name)?.description ?? '', usesTokens: false })),
201  ].map(m => {
202    const own = installed.get(m.name)
203    const status: ModStatus = own === undefined ? 'available' : own.enabled === false ? 'off' : 'on'
204
205    return { ...m, status, version: own?.version, latest: newer(m.name, own?.version), scope: own?.scope, projectPath: own?.projectPath || undefined }
206  })
207  await update($, rows, () => next)
208}
209
210/** Installs, enables, disables, updates or removes one mod; returns false when the CLI refused. */
211async function change($: EngineInterface, row: ModRow, action: Action) {
212  const id = `${row.name}@${MARKETPLACE}`
213  const scope = row.scope !== undefined && action !== 'install' ? ['--scope', row.scope] : []
214  const cwd = action === 'install' ? undefined : row.projectPath
215  const result = await cli($, ['plugin', action, id, ...scope], 120000, cwd).catch((error: unknown) => ({ exitCode: 1, stdout: '', stderr: String(error) }))
216  if (result.exitCode !== 0) {
217    await update($, message, () => `${action} ${row.name} failed: ${(result.stderr || result.stdout).trim().split('\n').at(-1)?.slice(0, 200) ?? 'unknown error'}`)
218    return false
219  }
220
221  return true
222}
223
224async function act($: EngineInterface, row: ModRow, action: Action) {
225  if ((await read($, busy)) !== null) return
226  if (action === 'uninstall') {
227    const answer = await $.ui.ask(`Remove ${row.name}? Its settings stay saved; you can install it again any time.`, { header: 'Mods', options: ['Remove', 'Keep it'] }).catch(() => 'Keep it')
228    if (answer !== 'Remove') return
229  }
230  await update($, busy, () => row.name)
231  await update($, message, () => '')
232  try {
233    if (await change($, row, action)) {
234      await update($, needsRestart, () => true)
235      const done = { uninstall: 'removed', install: 'installed', enable: 'turned on', disable: 'turned off', update: `updated to ${row.latest ?? 'the latest version'}` }[action]
236      $.ui.toast(`${GLYPH.ok} ${row.name}: ${done}. Applies in your next session.`)
237    }
238    await refresh($)
239  } finally {
240    await update($, busy, () => null)
241  }
242}
243
244/** Updates every mod that has a newer version in the marketplace. */
245async function updateAll($: EngineInterface) {
246  const outdated = [...(await read($, rows)), ...[await read($, self)].filter((r): r is ModRow => r !== null)].filter(r => r.latest !== undefined)
247  if (outdated.length === 0 || (await read($, busy)) !== null) return
248  await update($, busy, () => `${outdated.length} update${outdated.length === 1 ? '' : 's'}`)
249  await update($, message, () => '')
250  let changed = 0
251  try {
252    for (const row of outdated) if (await change($, row, 'update')) changed++
253    if (changed > 0) {
254      await update($, needsRestart, () => true)
255      $.ui.toast(`${GLYPH.ok} Updated ${changed} mod${changed === 1 ? '' : 's'}. Applies in your next session.`)
256    }
257    await refresh($)
258  } finally {
259    await update($, busy, () => null)
260  }
261}
262
263/** Fetches the marketplace's latest catalog, then re-reads what is installed, so "update available" is current. */
264async function checkForUpdates($: EngineInterface) {
265  if ((await read($, busy)) !== null) return
266  await update($, busy, () => 'checking for updates')
267  try {
268    const result = await cli($, ['plugin', 'marketplace', 'update', MARKETPLACE], 120000).catch((error: unknown) => ({ exitCode: 1, stdout: '', stderr: String(error) }))
269    if (result.exitCode !== 0) {
270      await update($, message, () => `Couldn't check for updates: ${(result.stderr || result.stdout).trim().split('\n').at(-1)?.slice(0, 200) ?? 'unknown error'}`)
271    }
272    await refresh($)
273  } finally {
274    await update($, busy, () => null)
275  }
276}
277
278/** Makes the installed set match a preset: installs or turns on what it lists, turns off the rest (nothing is removed). */
279async function applyPreset($: EngineInterface, presetId: string) {
280  const preset = PRESETS.find(p => p.id === presetId)
281  if (preset === undefined || (await read($, busy)) !== null) return
282  await update($, busy, () => preset.label)
283  await update($, message, () => '')
284  let changed = 0
285  try {
286    for (const row of await read($, rows)) {
287      const wanted = preset.mods.includes(row.name)
288      const action = wanted ? (row.status === 'available' ? 'install' : row.status === 'off' ? 'enable' : null) : row.status === 'on' ? 'disable' : null
289      if (action === null) continue
290      if (await change($, row, action)) changed++
291    }
292    if (changed > 0) {
293      await update($, needsRestart, () => true)
294      $.ui.toast(`${preset.label}: ${changed} change${changed === 1 ? '' : 's'}. Applies in your next session.`)
295    } else {
296      $.ui.toast(`${preset.label} is already what you have.`)
297    }
298    await refresh($)
299  } finally {
300    await update($, busy, () => null)
301  }
302}
303
304export const register: Register = (on, options) => {
305  cliPath = typeof options.cliPath === 'string' && options.cliPath.trim() !== '' ? options.cliPath.trim() : 'claude'
306
307  on('session.start', async ($, e, next) => {
308    await $.command.register({ name: 'mods', description: 'Choose which claude-mods to install and turn on' })
309    // One hello on the very first session after install; never again.
310    if ((await $.store.get('welcomed')) !== true) {
311      await $.store.set('welcomed', true)
312      $.ui.toast('claude-mods ready: /mods to pick your set. Useful? A star on GitHub helps others find it.', { timeoutMs: 10000 })
313    }
314
315    return next(e)
316  })
317
318  on('command.run', { command: 'mods' }, async $ => {
319    await $.ui.open({ id: PANE, title: 'Mods' })
320    // Offline: compares with the marketplace copy Claude Code keeps. Fetching news is the Check for updates button.
321    void refresh($)
322
323    return { text: 'Mod manager opened.' }
324  })
325
326  on('ui.render', { component: 'Pane', requestId: PANE }, async ($, e) => {
327    const { Box, Text, Button } = $.ui.resolve(e)
328    const kit = { Box, Text }
329    const list = await read($, rows)
330    const me = await read($, self)
331    const working = await read($, busy)
332    const note = await read($, message)
333    const restart = await read($, needsRestart)
334    const onCount = list.filter(r => r.status === 'on').length
335    const updates = [...list, ...(me !== null ? [me] : [])].filter(r => r.latest !== undefined).length
336    const icon: Record<ModStatus, string> = { on: GLYPH.on, off: GLYPH.off, available: GLYPH.off }
337    const color: Record<ModStatus, string> = { on: TONE.accent, off: TONE.dim, available: TONE.dim }
338    const status =
339      working !== null
340        ? `working on ${working}…`
341        : list.length === 0
342          ? 'reading what is installed…'
343          : `${onCount} on of ${list.length}${updates > 0 ? ` · ${updates} update${updates === 1 ? '' : 's'} available` : ''}`
344    const version = (r: ModRow) =>
345      r.version === undefined ? null : r.latest !== undefined ? <Text color={TONE.accent}>{`${r.version} → ${r.latest}`}</Text> : <Text dimColor>{r.version}</Text>
346
347    return (
348      <Box flexDirection="column" gap={1}>
349        <Box flexDirection="column">
350          {header(kit, note !== '' ? GLYPH.fail : updates > 0 ? GLYPH.warn : GLYPH.on, note !== '' ? TONE.bad : updates > 0 ? TONE.warn : TONE.accent, 'mod-manager', status)}
351          {restart && (
352            <Text color={TONE.warn}>
353              {GLYPH.warn} Changes apply in your next session (start a new chat or restart Claude Code).
354            </Text>
355          )}
356          {note !== '' && (
357            <Text color={TONE.bad}>
358              {GLYPH.fail} {note}
359            </Text>
360          )}
361          {list.length === 0 && note === '' && empty(kit, 'Asking Claude Code which mods are installed… this takes a few seconds.')}
362        </Box>
363
364        {updates > 0 && (
365          <Box gap={1}>
366            <Button key="update-all" hotkey="u" variant="primary" label={`Update ${updates === 1 ? '1 mod' : `all ${updates}`}`} onPress={() => void updateAll($)} />
367            <Text dimColor>Takes effect in your next session.</Text>
368          </Box>
369        )}
370
371        {section(
372          kit,
373          "Presets (turns off what isn't listed, removes nothing)",
374          <Box gap={1} flexWrap="wrap">
375            {PRESETS.map((p, i) => (
376              <Button key={`preset-${p.id}`} plain hotkey={String(i + 1)} label={p.label} onPress={() => void applyPreset($, p.id)} />
377            ))}
378          </Box>,
379        )}
380
381        {me !== null && me.latest !== undefined &&
382          section(
383            kit,
384            'This manager',
385            <Box gap={1}>
386              <Text color={TONE.accent}>{GLYPH.on}</Text>
387              <Text bold>mod-manager</Text>
388              {version(me)}
389              <Button key="update-mod-manager" plain label="Update" onPress={() => void act($, me, 'update')} />
390            </Box>,
391          )}
392
393        {list.length > 0 &&
394          section(
395            kit,
396            'Mods',
397            list.map(r => (
398              <Box flexDirection="column">
399                <Box gap={1}>
400                  <Text color={color[r.status]}>{icon[r.status]}</Text>
401                  <Text bold>{r.name}</Text>
402                  {version(r)}
403                  {r.usesTokens && <Text color={TONE.warn}>uses tokens</Text>}
404                  {r.latest !== undefined && <Button key={`update-${r.name}`} plain label="Update" onPress={() => void act($, r, 'update')} />}
405                  {r.status === 'available' && <Button key={`install-${r.name}`} plain label="Install" onPress={() => void act($, r, 'install')} />}
406                  {r.status === 'off' && <Button key={`enable-${r.name}`} plain label="Turn on" onPress={() => void act($, r, 'enable')} />}
407                  {r.status === 'on' && <Button key={`disable-${r.name}`} plain label="Turn off" onPress={() => void act($, r, 'disable')} />}
408                  {r.status !== 'available' && <Button key={`remove-${r.name}`} plain label="Remove" onPress={() => void act($, r, 'uninstall')} />}
409                </Box>
410                {r.blurb !== '' && (
411                  <Box paddingLeft={2}>
412                    <Text dimColor wrap="truncate-end">
413                      {r.blurb}
414                    </Text>
415                  </Box>
416                )}
417              </Box>
418            )),
419          )}
420
421        <Box gap={1}>
422          <Button key="refresh" hotkey="r" label="Refresh" onPress={() => void refresh($)} />
423          <Button key="check" label="Check for updates" onPress={() => void checkForUpdates($)} />
424        </Box>
425      </Box>
426    )
427  })
428}
429

1export type ModStatus = 'on' | 'off' | 'available'
2
3export type ModRow = {
4  name: string
5  blurb: string
6  usesTokens: boolean
7  status: ModStatus
8  version?: string
9  /** A newer version in the marketplace, when there is one. */
10  latest?: string
11  scope?: string
12  /** The folder a local or project install belongs to; the CLI is run from there. */
13  projectPath?: string
14}
15
16declare module 'claude-code' {
17  interface PluginState {
18    'mod-manager': {
19      rows: ModRow[]
20      busy: string | null
21      message: string
22      needsRestart: boolean
23      /** mod-manager's own install, shown only when it has an update. */
24      self: ModRow | null
25    }
26  }
27}
28