pstack

1import { atom, read, update } from 'claude-code'
2import type { EngineInterface, Register } from 'claude-code'
3
4import type { PstackLoaded, PstackSkill } from '../types'
5import { descriptionFrom, grouped } from './catalog'
6import { POTETO_OFF, potetoSection, storeKey } from './poteto'
7import { agentModel, agentType, harnessNote, modelsFrom } from './translate'
8
9// The org's security plugin can bypass user-tier skill.prompt hooks, so the note rides prompt.submit and Read instead
10const PSTACK_COMMAND = /^\/pstack:(\S+)/
11const PANE = 'pstack'
12const HIDDEN_KEY = 'hidden'
13const LOADED_TAB = 'Loaded'
14const LOADED_NOTES: Record<PstackLoaded['via'], string> = {
15  read: 'read this session',
16  run: 'run this session',
17  skill: 'loaded by Claude this session',
18}
19const WORDMARK =['█▀█ █▀ ▀█▀ ▄▀█ █▀▀ █▄▀', '█▀▀ ▄█  █  █▀█ █▄▄ █ █']
20
21const poteto = atom({ plugin: 'pstack', key: 'poteto' } as const, false)
22const skills = atom({ plugin: 'pstack', key: 'skills' } as const, [])
23const hidden = atom({ plugin: 'pstack', key: 'hidden' } as const, [])
24const group = atom({ plugin: 'pstack', key: 'group' } as const, '')
25const loaded = atom({ plugin: 'pstack', key: 'loaded' } as const, [])
26const pinned = atom({ plugin: 'pstack', key: 'pinned' } as const, false)
27
28// Mirrors the project's stored choice into session state, which prompt.submit reads
29async function loadPoteto($: EngineInterface, isDefault: boolean): Promise<boolean> {
30  const stored = await $.store.get(storeKey(await $.session.root()))
31  const isOn = typeof stored === 'boolean' ? stored : isDefault
32  await update($, poteto, () => isOn)
33
34  return isOn
35}
36
37async function togglePoteto($: EngineInterface, isDefault: boolean): Promise<void> {
38  const isOn = !(await loadPoteto($, isDefault))
39  await $.store.set(storeKey(await $.session.root()), isOn)
40  await update($, poteto, () => isOn)
41  $.ui.toast(isOn ? 'poteto mode on' : 'poteto mode off')
42}
43
44// Every folder under skills/ with its frontmatter description, read once per session
45async function loadSkills($: EngineInterface): Promise<void> {
46  const entries = await $.fs.list(`${$.plugin.root}/skills`).catch(() => [])
47  const found: PstackSkill[] = await Promise.all(
48    entries
49      .filter(entry => entry.kind === 'dir')
50      .map(async entry => ({
51        name: entry.name,
52        description: descriptionFrom(String(await $.fs.read(`${$.plugin.root}/skills/${entry.name}/SKILL.md`).catch(() => ''))),
53      })),
54  )
55  await update($, skills, () => found)
56
57  const stored = await $.store.get(HIDDEN_KEY)
58  await update($, hidden, () => (Array.isArray(stored) ? stored.filter(name => typeof name === 'string') : []))
59}
60
61// Only the pane header shows it, so a manifest that does not parse must not stop session.start
62function versionFrom(manifest: string): string {
63  try {
64    const version: unknown = JSON.parse(manifest).version
65
66    return typeof version === 'string' ? version : ''
67  } catch {
68    return ''
69  }
70}
71
72async function markLoaded($: EngineInterface, name: string, via: PstackLoaded['via']): Promise<void> {
73  await update($, loaded, list => (list.some(one => one.name === name) ? list : [...list, { name, via }]))
74}
75
76async function toggleHidden($: EngineInterface, name: string): Promise<void> {
77  const next = await update($, hidden, names => (names.includes(name) ? names.filter(one => one !== name) : [...names, name]))
78  await $.store.set(HIDDEN_KEY, next)
79  $.ui.invalidate('command.describe')
80}
81
82export const register: Register = (on, options) => {
83  const models = modelsFrom(options)
84  const isPotetoDefault = options.poteto_default === true
85  // Loops (main is '') that already carry the note this turn
86  const noted = new Set<string>()
87  let potetoSkill = ''
88  let version = ''
89
90  on('session.start', async ($, e, next) => {
91    potetoSkill = String(await $.fs.read(`${$.plugin.root}/skills/poteto-mode/SKILL.md`).catch(() => ''))
92    version = versionFrom(String(await $.fs.read(`${$.plugin.root}/.claude-plugin/plugin.json`).catch(() => '')))
93    await update($, loaded, () => [])
94    await update($, pinned, () => false)
95    await $.command.register({ name: 'poteto', description: 'Toggle poteto mode for this project' })
96    await $.command.register({ name: 'pstack', description: 'Browse, run and hide pstack skills' })
97    await loadPoteto($, isPotetoDefault)
98    await loadSkills($)
99
100    return next(e)
101  })
102
103  on('command.run', { command: 'poteto' }, async $ => {
104    await togglePoteto($, isPotetoDefault)
105
106    return {}
107  })
108
109  on('command.run', { command: 'pstack' }, async $ => {
110    await $.ui.open({ id: PANE, title: 'pstack', closeOnEscape: true })
111
112    return { text: 'pstack pane opened' }
113  })
114
115  on('command.describe', async ($, e, next) => {
116    const name = e.command.startsWith('pstack:') ? e.command.slice('pstack:'.length) : undefined
117
118    if (name === undefined || !(await read($, hidden)).includes(name)) {
119      return next(e)
120    }
121
122    return next({ ...e, isHidden: true })
123  })
124
125  on('turn.start', ($, e, next) => {
126    noted.clear()
127
128    return next(e)
129  })
130
131  on('prompt.submit', async ($, e, next) => {
132    const command = e.text.match(PSTACK_COMMAND)?.[1]
133    const context = [...(e.context ?? [])]
134
135    if (command !== undefined) {
136      noted.add('')
137      await markLoaded($, command, 'run')
138      context.push(harnessNote($.plugin.root, models))
139    }
140
141    // The conversation catches up with the toggle on the next prompt the model reads
142    if (command !== undefined || !e.text.startsWith('/')) {
143      const isOn = await read($, poteto)
144
145      if (isOn !== (await read($, pinned))) {
146        context.push(isOn ? potetoSection($.plugin.root, potetoSkill, harnessNote($.plugin.root, models)) : POTETO_OFF)
147        await update($, pinned, () => isOn)
148      }
149    }
150
151    return next(context.length === (e.context ?? []).length ? e : { ...e, context })
152  })
153
154  on('tool.call', { tool: 'Read' }, async ($, e, next) => {
155    const result = await next(e)
156    const loop = e.agentId ?? ''
157    const skillsDir = `${$.plugin.root}/skills/`
158    const isPstackFile = e.file_path.startsWith(skillsDir) || e.file_path.startsWith(`${$.plugin.root}/agents/`)
159
160    // A subagent's reads sit in its own context, not the conversation the pane reports on
161    if (e.file_path.startsWith(skillsDir) && result.deny === undefined && e.agentId === undefined) {
162      await markLoaded($, e.file_path.slice(skillsDir.length).split('/')[0] ?? '', 'read')
163    }
164
165    if (!isPstackFile || result.deny !== undefined || noted.has(loop)) {
166      return result
167    }
168
169    noted.add(loop)
170
171    return { ...result, context: [...(result.context ?? []), harnessNote($.plugin.root, models)] }
172  })
173
174  on('tool.call', { tool: 'Skill' }, async ($, e, next) => {
175    const result = await next(e)
176    const name = e.skill.match(/^pstack:(principle-[a-z-]+)$/)?.[1]
177
178    if (name !== undefined && result.deny === undefined && e.agentId === undefined) {
179      await markLoaded($, name, 'skill')
180    }
181
182    return result
183  })
184
185  on('session.compact', async ($, e, next) => {
186    const result = await next(e)
187
188    if (e.agentId === undefined && e.trigger !== 'precompute' && !('skip' in result)) {
189      await update($, loaded, () => [])
190      await update($, pinned, () => false)
191    }
192
193    return result
194  })
195
196  on('agent.spawn', ($, e, next) =>
197    next({ ...e, subagentType: agentType(e.subagentType), model: agentModel(e.model, models) }),
198  )
199
200  // Draws the footer's modes itself: the desktop skips plain mode labels, and the poteto one is a toggle
201  on('ui.render', { component: 'SessionMode' }, async ($, e) => {
202    const { Box, Button, Text } = $.ui.resolve(e)
203    const isOn = await read($, poteto)
204
205    return (
206      <Box flexDirection="row">
207        {e.props.modes.map(mode => (
208          <Text key={mode} dimColor>
209            {mode} &{' '}
210          </Text>
211        ))}
212        <Button
213          key="poteto"
214          variant="primary"
215          dimColor={!isOn}
216          label="poteto"
217          onPress={() => void togglePoteto($, isPotetoDefault)}
218        />
219        <Text color={isOn ? 'success' : undefined} dimColor={!isOn}>
220          {isOn ? ' ♛ on' : ' ♛ off'}
221        </Text>
222      </Box>
223    )
224  })
225
226  on('ui.render', { component: 'Pane', requestId: PANE }, async ($, e) => {
227    const { Box, Button, Text } = $.ui.resolve(e)
228    const all = await read($, skills)
229    const hiddenNames = await read($, hidden)
230    const isOn = await read($, poteto)
231
232    if (all.length === 0) {
233      return <Text dimColor>No pstack skills found under {$.plugin.root}/skills.</Text>
234    }
235
236    const isPinned = await read($, pinned)
237    const pinnedRows = isPinned ? [{ name: 'poteto-mode', note: 'in context while poteto is on' }] : []
238    const sessionLoaded = (await read($, loaded))
239      .filter(one => !(isPinned && one.name === 'poteto-mode'))
240      .map(one => ({ name: one.name, note: LOADED_NOTES[one.via] }))
241    const loadedRows = [...pinnedRows, ...sessionLoaded]
242    const loadedNames = new Set(loadedRows.map(one => one.name))
243
244    const groups = grouped(all).slice(0, 8)
245    const tabs = [...groups.map(one => ({ title: one.title, label: one.title })), { title: LOADED_TAB, label: `${LOADED_TAB} ${loadedRows.length}` }]
246    const chosen = await read($, group)
247    const selected = tabs.find(one => one.title === chosen) ?? tabs[0]
248    const rows =
249      selected?.title === LOADED_TAB
250        ? loadedRows.map(one => ({ name: one.name, description: one.note }))
251        : (groups.find(one => one.title === selected?.title)?.skills ?? [])
252
253    return (
254      <Box flexDirection="column">
255        <Box flexDirection="column">
256          {WORDMARK.map((line, index) => (
257            <Text key={`wordmark-${index}`} color="warning">
258              {line}
259            </Text>
260          ))}
261          <Text color={isOn ? 'success' : undefined} dimColor={!isOn} wrap="truncate-end">
262            {isOn ? '♛ poteto on: poteto-mode rides the conversation, every task gets the playbooks' : '♛ poteto off: /poteto or the footer toggle pins poteto-mode'}
263          </Text>
264          <Text dimColor wrap="truncate-end">
265            new here? press 1, then /poteto-help
266          </Text>
267          <Text dimColor wrap="truncate-end">
268            {`${loadedRows.length} loaded · ${hiddenNames.length} hidden · ${all.length} skills${version === '' ? '' : ` · v${version}`}`}
269          </Text>
270        </Box>
271        <Box flexDirection="row" flexWrap="wrap" columnGap={2} marginTop={1}>
272          {tabs.map((tab, index) => {
273            const isSelected = tab.title === selected?.title
274            const hotkey = String(index + 1)
275            // The terminal draws a plain Button with a hotkey as `1: label`
276            const width = hotkey.length + 2 + tab.label.length
277
278            return (
279              <Box key={`tab-${tab.title}`} flexDirection="column">
280                <Button
281                  key={`group-${tab.title}`}
282                  plain
283                  hotkey={hotkey}
284                  dimColor={!isSelected}
285                  label={tab.label}
286                  onPress={() => void update($, group, () => tab.title)}
287                />
288                <Text color={isSelected ? 'suggestion' : undefined} dimColor={!isSelected}>
289                  {(isSelected ? '━' : '─').repeat(width)}
290                </Text>
291              </Box>
292            )
293          })}
294        </Box>
295        <Box flexDirection="column" marginTop={1}>
296          {rows.length === 0 && <Text dimColor>No pstack skill is in the context yet.</Text>}
297          {rows.map(skill => {
298            const isHidden = hiddenNames.includes(skill.name)
299            const isLoaded = loadedNames.has(skill.name)
300
301            return (
302              <Box key={skill.name} flexDirection="row" gap={1}>
303                <Text color={isLoaded ? 'success' : undefined}>{isLoaded ? '●' : ' '}</Text>
304                <Button
305                  key={`run-${skill.name}`}
306                  plain
307                  dimColor={isHidden}
308                  label={`/${skill.name}`}
309                  onPress={() => void $.prompt.fill({ text: `/pstack:${skill.name} `, mode: 'replace' })}
310                />
311                <Box flexGrow={1} flexShrink={1} overflow="hidden">
312                  <Text dimColor wrap="truncate-end">
313                    {skill.description}
314                  </Text>
315                </Box>
316                <Button
317                  key={`hide-${skill.name}`}
318                  plain
319                  dimColor
320                  label={isHidden ? 'show' : 'hide'}
321                  onPress={() => void toggleHidden($, skill.name)}
322                />
323              </Box>
324            )
325          })}
326        </Box>
327        <Box marginTop={1}>
328          <Text dimColor>Press a skill to put it in the prompt · 1-9 switch tabs · hidden skills stay out of the / menu but still run when typed</Text>
329        </Box>
330      </Box>
331    )
332  })
333}
334

1// The /pstack pane's grouping of upstream skills; a skill upstream adds later lands in Other until it is placed here
2
3import type { PstackSkill } from '../types'
4
5const GROUPS: ReadonlyArray<readonly [string, readonly string[]]> = [
6  ['Start here', ['poteto-mode', 'poteto-help']],
7  ['Understand', ['how', 'why', 'teach', 'recall', 'blast-radius', 'bro']],
8  ['Design', ['architect', 'arena', 'interrogate', 'figure-it-out']],
9  [
10    'Build and verify',
11    ['tdd', 'swarm', 'create-verification-skill', 'maintain-verification-skill', 'benchmark-checklist', 'show-me-your-work'],
12  ],
13  ['Clean and write', ['unslop', 'no-comments', 'technical-writing', 'typescript-best-practices']],
14  ['Improve the setup', ['correct', 'reflect', 'automate-me']],
15]
16
17export type Group = { title: string; skills: PstackSkill[] }
18
19export function descriptionFrom(skill: string): string {
20  const frontmatter = skill.match(/^---\n([\s\S]*?)\n---/)?.[1] ?? ''
21  const description = frontmatter.match(/^description:\s*(.+)$/m)?.[1]?.trim() ?? ''
22
23  return description.replace(/^(["'])(.*)\1$/, '$2')
24}
25
26function groupOf(name: string): string {
27  if (name.startsWith('principle-')) {
28    return 'Principles'
29  }
30
31  return GROUPS.find(([, names]) => names.includes(name))?.[0] ?? 'Other'
32}
33
34export function grouped(skills: readonly PstackSkill[]): Group[] {
35  const titles = [...GROUPS.map(([title]) => title), 'Principles', 'Other']
36  const order = (name: string) => GROUPS.flatMap(([, names]) => names).indexOf(name)
37
38  return titles
39    .map(title => ({
40      title,
41      skills: skills
42        .filter(skill => groupOf(skill.name) === title)
43        .sort((a, b) => order(a.name) - order(b.name) || a.name.localeCompare(b.name)),
44    }))
45    .filter(group => group.skills.length > 0)
46}
47

1// Cursor pins poteto mode's SKILL.md as a Custom Mode. Desktop sessions raise no prompt.compose, so here it rides a prompt's context once
2
3export function potetoSection(root: string, skill: string, note: string): string {
4  const body = skill.replace(/^---\n[\s\S]*?\n---\n*/, '').trim()
5
6  return [
7    `Poteto mode is on for this project. Follow the poteto-mode skill below on every turn until a later note says poteto mode is off; no Read of its SKILL.md needed. Its playbooks and references live under \`${root}/skills/poteto-mode/\`.`,
8    note,
9    body,
10  ].join('\n\n')
11}
12
13export const POTETO_OFF = 'Poteto mode is now off for this project. Stop following the poteto-mode skill given earlier in this conversation and work in your normal style.'
14
15export function storeKey(projectRoot: string): string {
16  return `poteto:${projectRoot}`
17}
18

1// Pure mapping from upstream's Cursor vocabulary to Claude Code, kept free of `$` so tests can call it directly
2
3export type Models = {
4  search: string
5  code: string
6  judgment: string
7}
8
9const AGENT_TYPES: Record<string, string> = {
10  generalPurpose: 'general-purpose',
11  'poteto-agent': 'pstack:poteto-agent',
12  'Comment Sicko': 'pstack:Comment Sicko',
13}
14
15const INHERIT = new Set(['inherit', 'inherit-parent', 'auto'])
16
17export function modelsFrom(options: Readonly<Record<string, unknown>>): Models {
18  const pick = (key: string, fallback: string) => (typeof options[key] === 'string' ? (options[key] as string) : fallback)
19
20  return {
21    search: pick('search_model', 'haiku'),
22    code: pick('code_model', 'sonnet'),
23    judgment: pick('judgment_model', 'opus'),
24  }
25}
26
27export function agentType(type: string): string {
28  return AGENT_TYPES[type] ?? type
29}
30
31// undefined means omit `model`, so the subagent runs on its own or the parent's model
32export function agentModel(model: string | undefined, models: Models): string | undefined {
33  if (model === undefined || INHERIT.has(model)) {
34    return undefined
35  }
36
37  const mapped = model.startsWith('grok-') ? models.code : model.startsWith('claude-opus-') ? models.judgment : model
38
39  return INHERIT.has(mapped) ? undefined : mapped
40}
41
42function named(model: string): string {
43  return INHERIT.has(model) ? 'the parent model (omit `model`)' : `\`${model}\``
44}
45
46export function harnessNote(root: string, models: Models): string {
47  return [
48    'pstack was written for Cursor. You are in Claude Code, so translate its instructions as you follow them:',
49    `- Another pstack skill: Read \`${root}/skills/<name>/SKILL.md\` and follow it. Principles are the exception: load one with the Skill tool as \`pstack:principle-<slug>\`. The Skill tool refuses every other pstack skill. Read pstack files one per Read call, in parallel when there are several, never through \`cat\`, \`sed\` or \`head\` in Bash.`,
50    '- `Task` tool or call: the `Agent` tool. Subagent types: `generalPurpose` is `general-purpose`, `poteto-agent` is `pstack:poteto-agent`, `Comment Sicko` is `pstack:Comment Sicko`. Readonly agent mode: the `Explore` agent. `environment: "cloud"`: `isolation: "worktree"`.',
51    '- `AskQuestion`: `AskUserQuestion`.',
52    `- Models: \`~/.cursor/rules/pstack-models.mdc\` and \`/setup-pstack\` do not exist here, so use the defaults below. Grok slugs mean ${named(models.code)}. \`claude-opus-*\` slugs mean ${named(models.judgment)}. Fast searches (the recall fan-out, readonly exploration) use ${named(models.search)}. \`inherit\`, \`inherit-parent\` and \`auto\` mean omit \`model\`. A panel of Opus and Grok is one judgment-model and one code-model agent.`,
53    '- Not available: cursor-team-kit (`deslop`, `control-ui`, `control-cli`), `/make-bot-ui`, and Cursor\'s `create-skill` (use `skill-creator` if installed). Use the project\'s own verification skill or browser tools instead, and say what you skipped.',
54    "- The user's CLAUDE.md files and rules win over pstack's Autonomy guidance. If they say never commit, do not commit.",
55  ].join('\n')
56}
57

1// Whether poteto mode is on for the session's project, mirrored from $.store
2export type PstackPoteto = boolean
3
4// One skill folder under skills/, as the /pstack pane lists it
5export type PstackSkill = { name: string; description: string }
6
7// A pstack skill whose text sits in the main conversation: its files read, or typed as /pstack:<name>
8export type PstackLoaded = { name: string; via: 'read' | 'run' | 'skill' }
9
10declare module 'claude-code' {
11  interface PluginState {
12    pstack: {
13      poteto: PstackPoteto
14      skills: PstackSkill[]
15      // Skill names hidden from the / menu, mirrored from $.store
16      hidden: string[]
17      // The group the /pstack pane shows on the right; '' is the first group
18      group: string
19      // Cleared at compaction and at session start; the pinned poteto-mode is derived from poteto instead
20      loaded: PstackLoaded[]
21      // Whether the conversation holds the poteto-mode text; cleared at compaction and session start
22      pinned: boolean
23    }
24  }
25}
26