handoff-on-clear

1import { atom, read, update } from 'claude-code'
2import type { EngineInterface, Register } from 'claude-code'
3
4import type { Handoff } from '../types'
5
6// Before /clear (or exit) wipes the context, save what the next session needs:
7// the last answer, recent asks, open PRs, artifact links, and optionally a
8// short summary from one cached fork. Offer it back on the next prompt.
9
10const pending = atom({ plugin: 'handoff-on-clear', key: 'pending' } as const, null)
11const willAttach = atom({ plugin: 'handoff-on-clear', key: 'willAttach' } as const, false)
12
13const MAX_AGE_MS = 3 * 24 * 3600_000
14const ASKS_FOR_IT = /prompt to (restart|continue|complete|resume)|lost (you|your)|redisplay|pull up|where were we|carry on/i
15const SUMMARY_PROMPT =
16  'The user is about to clear this conversation. Write a handoff for a fresh session, under 200 words, plain markdown: ' +
17  'the goal, what is done (PR numbers, merged or open), the exact next step, and any gotchas or decisions made. No preamble.'
18
19function storeKey(cwd: string) {
20  return `handoff:${cwd}`
21}
22
23async function consume($: EngineInterface) {
24  await update($, pending, () => null)
25  await update($, willAttach, () => false)
26  await $.store.delete(storeKey(await $.session.cwd()))
27}
28
29async function snapshot($: EngineInterface, reason: string): Promise<Handoff | undefined> {
30  const messages = await $.session.messages()
31  if (!Array.isArray(messages) || messages.length < 2) return undefined
32
33  const recent = messages.slice(-60)
34  const all = recent.map(m => m.text ?? '').join('\n')
35  const lastAnswer = [...recent].reverse().find(m => m.role === 'assistant' && (m.text ?? '').trim() !== '')?.text ?? ''
36  const prompts = recent
37    .filter(m => m.role === 'user' && (m.text ?? '').trim() !== '' && !(m.text ?? '').startsWith('<'))
38    .map(m => (m.text ?? '').trim().slice(0, 200))
39    .slice(-6)
40  const links = [...new Set(all.match(/https:\/\/claude\.ai\/(code\/)?artifact\/[\w-]+/g) ?? [])].slice(-5)
41  const prs = [...new Set(all.match(/(?:PR\s*)?#\d{2,5}\b|\/pull\/\d+/g) ?? [])]
42    .map(p => `#${p.replace(/\D/g, '')}`)
43  const branch = await $.process.run(['git', 'rev-parse', '--abbrev-ref', 'HEAD'])
44    .then(r => (r.exitCode === 0 ? r.stdout.trim() : ''))
45    .catch(() => '')
46
47  return {
48    cwd: await $.session.cwd(),
49    savedAt: await $.clock.now(),
50    reason,
51    branch,
52    summary: '',
53    lastAnswer: lastAnswer.slice(0, 4000),
54    prompts,
55    links,
56    prs: [...new Set(prs)].slice(-10),
57  }
58}
59
60function render(ho: Handoff): string {
61  const parts = ['[handoff-on-clear] Context saved from the previous session in this directory.']
62  if (ho.summary) parts.push(`## Summary\n${ho.summary}`)
63  if (ho.branch) parts.push(`Branch at the time: ${ho.branch}`)
64  if (ho.prs.length) parts.push(`PRs mentioned: ${ho.prs.join(', ')}`)
65  if (ho.links.length) parts.push(`Artifacts: ${ho.links.join(' ')}`)
66  if (ho.prompts.length) parts.push(`## Last asks\n${ho.prompts.map(p => `- ${p}`).join('\n')}`)
67  if (ho.lastAnswer) parts.push(`## Last answer\n${ho.lastAnswer}`)
68  return parts.join('\n\n')
69}
70
71function headline(ho: Handoff): string {
72  const first = (ho.summary || ho.prompts.at(-1) || ho.lastAnswer).split('\n').find(l => l.trim() !== '') ?? ''
73  return first.replace(/^[#*\-\s]+/, '').slice(0, 90)
74}
75
76export const register: Register = (on, options) => {
77  const summarize = options.summarize !== false
78
79  on('session.start', async ($, e, next) => {
80    await $.command.register({
81      name: 'handoff',
82      description: 'Show the saved handoff for this directory and give it to Claude',
83    })
84    const saved = (await $.store.get(storeKey(e.cwd))) as Handoff | undefined
85    if (saved && (await $.clock.now()) - saved.savedAt < MAX_AGE_MS) {
86      await update($, pending, () => saved)
87    }
88    return next(e)
89  })
90
91  on('session.end', async ($, e, next) => {
92    if (e.reason !== 'clear' && e.reason !== 'prompt_input_exit') return next(e)
93    const ho = await snapshot($, e.reason)
94    if (!ho) return next(e)
95
96    if (summarize) {
97      const reply = await $.model.fork({ prompt: SUMMARY_PROMPT })
98      if (reply.isAnswered) ho.summary = reply.text.trim()
99    }
100    await $.store.set(storeKey(ho.cwd), ho)
101    // After /clear the process goes on: offer it straight away.
102    await update($, pending, () => ho)
103    await update($, willAttach, () => false)
104    $.ui.toast('Handoff saved: it will be offered on your next prompt')
105
106    return next(e)
107  })
108
109  on('command.run', { command: 'handoff' }, async $ => {
110    const ho = await read($, pending)
111    if (!ho) return { text: 'No handoff saved for this directory.' }
112    await consume($)
113    return { text: render(ho) }
114  })
115
116  on('prompt.submit', async ($, e, next) => {
117    const ho = await read($, pending)
118    if (!ho || e.origin.kind !== 'composer') return next(e)
119    const isWanted = (await read($, willAttach)) || ASKS_FOR_IT.test(e.text)
120    if (!isWanted) return next(e)
121
122    await consume($)
123    return next({ ...e, context: [...(e.context ?? []), render(ho)] })
124  })
125
126  on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
127    const ho = await read($, pending)
128    if (!ho || e.props.hasSurvey) return next(e)
129    const isQueued = await read($, willAttach)
130    const { Box, Button, Text } = $.ui.resolve(e)
131
132    return (
133      <Box>
134        <Text color="cyan">↺ </Text>
135        <Text dimColor wrap="truncate">
136          {isQueued ? 'Handoff goes with your next prompt: ' : 'Handoff from last session: '}
137          {headline(ho)}{' '}
138        </Text>
139        {!isQueued && (
140          <Button key="load" label="Load" hotkey="l" variant="primary" onPress={() => update($, willAttach, () => true)} />
141        )}
142        <Button
143          key="dismiss"
144          label="Dismiss"
145          hotkey="d"
146          role="dismiss"
147          onPress={() => consume($)}
148        />
149      </Box>
150    )
151  })
152}
153

1export type Handoff = {
2  cwd: string
3  savedAt: number
4  reason: string
5  branch: string
6  summary: string
7  lastAnswer: string
8  prompts: string[]
9  links: string[]
10  prs: string[]
11}
12
13declare module 'claude-code' {
14  interface PluginState {
15    'handoff-on-clear': {
16      pending: Handoff | null
17      willAttach: boolean
18    }
19  }
20}
21