fork-explorer

1import { atom, read, update } from 'claude-code'
2import type { EngineInterface, Register } from 'claude-code'
3
4import type { Fork } from '../types'
5import { forkPrompt, parseApproaches, promptFor } from './approaches'
6
7const PANE = 'fork-explorer'
8const MAX_FORKS = 5
9const WIDE_ENOUGH = 100
10const forks = atom({ plugin: 'fork-explorer', key: 'forks' } as const, [])
11const viewing = atom({ plugin: 'fork-explorer', key: 'viewing' } as const, 0)
12
13const REASON_TEXT: Record<string, string> = {
14  'nothing-to-fork': 'There is no conversation to explore yet. Ask Claude something first.',
15  'api-error': 'The side question failed (API error). Try again.',
16  'empty-reply': 'The side question came back empty. Try rephrasing.',
17  aborted: 'The side question was cancelled.',
18}
19
20async function setFork($: EngineInterface, id: string, change: Partial<Fork>): Promise<void> {
21  await update($, forks, list => list.map(one => (one.id === id ? { ...one, ...change } : one)))
22}
23
24/** Runs one side question over the session and records its approaches. Never touches the conversation. */
25async function explore($: EngineInterface, question: string): Promise<Fork | undefined> {
26  const id = `fork-${await $.clock.now()}`
27  const fork: Fork = { id, question, status: 'thinking', approaches: [] }
28  await update($, forks, list => [fork, ...list].slice(0, MAX_FORKS))
29  await update($, viewing, () => 0)
30
31  const reply = await $.model.fork({ prompt: forkPrompt(question) })
32  if (!reply.isAnswered) {
33    await setFork($, id, { status: 'error', error: REASON_TEXT[reply.reason] ?? `No answer (${reply.reason}).` })
34  } else {
35    const approaches = parseApproaches(reply.text)
36    await setFork(
37      $,
38      id,
39      approaches.length === 0
40        ? { status: 'error', error: 'The answer could not be read as approaches. Try again.' }
41        : { status: 'done', approaches },
42    )
43  }
44  return (await read($, forks)).find(one => one.id === id)
45}
46
47export const register: Register = on => {
48  on('session.start', async ($, e, next) => {
49    await $.command.register({
50      name: 'fork',
51      description: 'Fork Explorer: "what if..." side question with 2-3 alternatives, kept out of the conversation',
52      argumentHint: '[what if...]',
53      immediate: true,
54    })
55
56    return next(e)
57  })
58
59  on('command.run', { command: 'fork' }, async ($, e) => {
60    await $.ui.open({ id: PANE, title: 'Fork Explorer', focus: true, closeOnEscape: true })
61    const question = e.args.trim()
62    if (question !== '') await explore($, question)
63
64    return {}
65  })
66
67  on('session.end', async ($, e, next) => {
68    if (e.reason === 'clear') await update($, forks, () => [])
69
70    return next(e)
71  })
72
73  on('ui.render', { component: 'Pane', requestId: PANE }, async ($, e) => {
74    const { Box, Button, Text } = $.ui.resolve(e)
75    const list = await read($, forks)
76    const at = Math.min(await read($, viewing), Math.max(0, list.length - 1))
77    const fork = list[at]
78    const isWide = e.props.bodyColumns >= WIDE_ENOUGH
79    const table = $.ui.resolve(e)
80    const ask =
81      'Input' in table ? (
82        <table.Input
83          key="ask"
84          label="What if…"
85          placeholder="we used Redis instead of Postgres for sessions?"
86          submitLabel="explore"
87          autoFocus
88          onSubmit={value => (value.trim() === '' ? undefined : void explore($, value.trim()))}
89        />
90      ) : null
91
92    return (
93      <Box flexDirection="column">
94        {ask}
95        {fork === undefined && (
96          <Text dimColor>Ask a "what if…" question. The answer stays here and never enters your conversation.</Text>
97        )}
98        {fork !== undefined && (
99          <Box flexDirection="column" marginTop={1}>
100            <Box flexDirection="row" gap={1}>
101              <Text bold wrap="truncate-end">
102                What if {fork.question}
103              </Text>
104              {list.length > 1 && (
105                <Text dimColor>
106                  ({at + 1}/{list.length})
107                </Text>
108              )}
109            </Box>
110            {fork.status === 'thinking' && <Text color="cyan">Exploring alternatives…</Text>}
111            {fork.status === 'error' && <Text color="red">{fork.error}</Text>}
112            {fork.status === 'done' && (
113              <Box flexDirection={isWide ? 'row' : 'column'} gap={1} marginTop={1}>
114                {fork.approaches.map((approach, index) => (
115                  <Box
116                    key={`card-${index}`}
117                    flexDirection="column"
118                    borderStyle="round"
119                    borderColor="cyan"
120                    paddingX={1}
121                    width={isWide ? `${Math.floor(100 / fork.approaches.length)}%` : undefined}
122                    flexGrow={1}
123                  >
124                    <Text bold color="cyan">
125                      {index + 1}. {approach.title}
126                    </Text>
127                    <Text dimColor>effort {approach.effort}</Text>
128                    <Text>{approach.idea}</Text>
129                    {approach.pros.map(pro => (
130                      <Text color="green">+ {pro}</Text>
131                    ))}
132                    {approach.cons.map(con => (
133                      <Text color="red">− {con}</Text>
134                    ))}
135                    <Button
136                      key={`use-${index}`}
137                      label="use this"
138                      hotkey={String(index + 1)}
139                      onPress={async () => {
140                        await $.prompt.fill({ text: promptFor(fork.question, approach), mode: 'replace' })
141                        $.ui.toast('Fork Explorer: put in your prompt. Edit it, then send.')
142                      }}
143                    />
144                  </Box>
145                ))}
146              </Box>
147            )}
148            <Box flexDirection="row" gap={1} marginTop={1}>
149              {at < list.length - 1 && (
150                <Button key="older" label="older" hotkey="o" onPress={() => update($, viewing, n => n + 1)} />
151              )}
152              {at > 0 && <Button key="newer" label="newer" hotkey="w" onPress={() => update($, viewing, n => n - 1)} />}
153              {fork.status !== 'thinking' && (
154                <Button key="again" label="ask again" hotkey="a" onPress={() => void explore($, fork.question)} />
155              )}
156            </Box>
157          </Box>
158        )}
159      </Box>
160    )
161  })
162}
163

1import type { Approach } from '../types'
2
3const MAX_APPROACHES = 3
4const MAX_TEXT = 400
5const MAX_ITEMS = 4
6
7export function forkPrompt(question: string): string {
8  return [
9    'Side question from the user. Answer it on its own: do not use tools and do not continue or change the current task.',
10    `What if: ${question}`,
11    'Give 2 or 3 genuinely different approaches, grounded in this conversation and codebase.',
12    'Reply with JSON only, no prose and no code fence, in exactly this shape:',
13    '{"approaches":[{"title":"short name","idea":"one or two sentences","pros":["..."],"cons":["..."],"effort":"S, M or L"}]}',
14  ].join('\n')
15}
16
17function text(value: unknown, limit = MAX_TEXT): string {
18  return typeof value === 'string' ? value.trim().slice(0, limit) : ''
19}
20
21function list(value: unknown): string[] {
22  return Array.isArray(value) ? value.map(item => text(item, 160)).filter(item => item !== '').slice(0, MAX_ITEMS) : []
23}
24
25/** Reads the approaches out of a reply, tolerating prose or a code fence around the JSON. */
26export function parseApproaches(reply: string): Approach[] {
27  const start = reply.indexOf('{')
28  const end = reply.lastIndexOf('}')
29  if (start < 0 || end <= start) return []
30
31  let parsed: unknown
32  try {
33    parsed = JSON.parse(reply.slice(start, end + 1))
34  } catch {
35    return []
36  }
37
38  const raw = (parsed as { approaches?: unknown }).approaches
39  if (!Array.isArray(raw)) return []
40
41  return raw
42    .map((item: Record<string, unknown>) => ({
43      title: text(item.title, 80),
44      idea: text(item.idea),
45      pros: list(item.pros),
46      cons: list(item.cons),
47      effort: text(item.effort, 8) || '?',
48    }))
49    .filter(approach => approach.title !== '' && approach.idea !== '')
50    .slice(0, MAX_APPROACHES)
51}
52
53/** The text "use this" puts in the prompt box for the person to edit and send. */
54export function promptFor(question: string, approach: Approach): string {
55  return `Let's go with "${approach.title}" for: ${question}\n${approach.idea}`
56}
57

1export type Approach = {
2  title: string
3  idea: string
4  pros: string[]
5  cons: string[]
6  effort: string
7}
8
9export type Fork = {
10  id: string
11  question: string
12  status: 'thinking' | 'done' | 'error'
13  approaches: Approach[]
14  error?: string
15}
16
17declare module 'claude-code' {
18  interface PluginState {
19    'fork-explorer': {
20      /** Newest first. */
21      forks: Fork[]
22      /** Index into forks of the one on screen. */
23      viewing: number
24    }
25  }
26}
27