handoff

1import { atom, update } from 'claude-code'
2import type { Register } from 'claude-code'
3
4import type { HandoffRun } from '../types'
5
6export const IDLE: HandoffRun = { phase: 'idle', summary: '', path: '' }
7
8const run = atom({ plugin: 'handoff', key: 'run' } as const, IDLE)
9
10export const PROMPT = `My context is getting full. Before we stop, write a handoff.md in the project root so a new session with zero memory of this conversation can pick up exactly where we left off. If handoff.md already exists, overwrite it completely — don't append, this one replaces it. Keep it short and concrete, not a full doc. Include:
11
12What we're doing: the task/feature in one or two sentences.
13Current state: what's done, what's half-done, what's broken right now.
14Next step: the exact next thing to do, specific enough to act on immediately.
15Decisions made: anything we chose along the way that isn't obvious from the code (and why, if it matters).
16Gotchas: anything that tripped us up or that the next session needs to know to avoid repeating a mistake.
17Open questions: anything still unresolved.
18Don't pad it or restate things that are obvious from reading the code. If something's already clear from the repo, skip it.`
19
20export const continuePrompt = (path: string) =>
21  `Read ${path} — it is the handoff from the previous session, which had to be cleared because its context was full. Then continue exactly where it left off, starting with its "Next step".`
22
23// Turns that may end before ours does (a turn already running when the button was pressed).
24const MAX_MISSES = 2
25
26// The flow in flight; module-level so a /clear in the middle of it doesn't lose it.
27let pending: { since: number; paths: string[]; misses: number } | null = null
28
29const join = (dir: string, name: string) => `${dir.replace(/[\\/]+$/, '')}${dir.includes('\\') ? '\\' : '/'}${name}`
30
31async function set($: any, next: HandoffRun): Promise<void> {
32  await update($, run, () => next)
33}
34
35// The handoff.md written since `since`, if any (project root first, then cwd).
36async function written($: any, paths: string[], since: number): Promise<string | null> {
37  for (const p of paths) {
38    try {
39      const s = await $.fs.stat(p)
40      // a little slack for file-system timestamp rounding
41      if (s.kind === 'file' && s.size > 0 && s.mtimeMs >= since - 2000) return p
42    } catch {
43      // not there
44    }
45  }
46  return null
47}
48
49async function start($: any): Promise<string> {
50  if (pending) return 'handoff: already in progress, waiting for handoff.md'
51  const root: string = await $.session.root()
52  const cwd: string = await $.session.cwd()
53  const paths = [...new Set([join(root, 'handoff.md'), join(cwd, 'handoff.md')])]
54  pending = { since: await $.clock.now(), paths, misses: 0 }
55  await set($, { phase: 'writing', summary: 'Claude is writing handoff.md…', path: paths[0] as string })
56  // A command hook can't submit (the submit would wait on the turn the hook holds), so a timer does.
57  $.clock.after(1, () => void $.prompt.submit({ text: PROMPT, asUser: true }))
58  return `handoff: asked Claude to write ${paths[0]}; will /clear and continue once it exists`
59}
60
61// /clear, then hand the fresh chat the file. Runs after the turn that wrote it has ended.
62async function clearAndContinue($: any, path: string): Promise<void> {
63  try {
64    await set($, { phase: 'clearing', summary: 'handoff.md written, clearing…', path })
65    await $.command.run({ command: 'clear' })
66    await $.prompt.submit({ text: continuePrompt(path), asUser: true })
67    await set($, { phase: 'done', summary: 'New chat is continuing from handoff.md', path })
68  } catch (err: any) {
69    await set($, { phase: 'error', summary: `handoff: ${String(err?.message ?? err)}`, path })
70  }
71}
72
73export const register: Register = on => {
74  on('session.start', async ($, e, next) => {
75    await $.command.register({
76      name: 'handoff',
77      description: 'Have Claude write handoff.md, then /clear and continue from it in a fresh chat',
78    })
79    return next(e)
80  })
81
82  on('command.run', { command: 'handoff' }, async $ => ({ text: await start($) }))
83
84  on('turn.complete', async ($, e, next) => {
85    const result = await next(e)
86    const p = pending
87    if (!p) return result
88    const path = await written($, p.paths, p.since)
89    if (path) {
90      pending = null
91      // on a timer: /clear can't run inside the turn's own completion
92      $.clock.after(300, () => void clearAndContinue($, path))
93    } else if (e.reason === 'aborted' || e.reason === 'error' || e.reason === 'refusal') {
94      pending = null
95      await set($, { phase: 'error', summary: `Handoff stopped: the turn ended (${e.reason}) before handoff.md was written`, path: p.paths[0] as string })
96    } else if (++p.misses >= MAX_MISSES) {
97      pending = null
98      await set($, { phase: 'error', summary: 'Handoff stopped: Claude finished without writing handoff.md', path: p.paths[0] as string })
99    }
100    return result
101  })
102}
103
104

1export type HandoffPhase = 'idle' | 'writing' | 'clearing' | 'done' | 'error'
2
3export type HandoffRun = {
4  phase: HandoffPhase
5  summary: string // one line shown in the sidebar
6  path: string // handoff.md being waited on
7}
8
9declare module 'claude-code' {
10  interface PluginState {
11    handoff: { run: HandoffRun }
12  }
13}
14