auto-handoff

1import { atom, read, update } from 'claude-code'
2import type { EngineInterface, Register } from 'claude-code'
3
4import type { WarnedAt } from '../types'
5
6/** 컨텍스트 사용률이 이 값(%)을 넘으면 /handoff 를 권한다. 이후 STEP %p 오를 때마다 다시 알린다. */
7export const WARN_AT: WarnedAt = 70
8// usage-hud 가 80%에서 알리므로 70%, 90%에 알려 겹치지 않게 한다.
9export const STEP = 20
10
11const warnedAt = atom({ plugin: 'auto-handoff', key: 'warnedAt' } as const, 0)
12
13const RULES = `# Auto-handoff
14- 큰 작업 단위가 끝났거나 사용자가 마무리 의사를 보이면 \`/handoff\` 실행을 한 줄로 제안한다.
15- 인수인계서는 \`.claude/handoff/HANDOFF.md\`, 수동 메모는 \`.claude/handoff/NOTES.md\`에 있다. 사용자가 이어서 하자고 하면 먼저 읽는다.`
16
17const ASK = `지금까지의 대화를 새 세션이 이어받을 수 있도록 인수인계서를 한국어 마크다운으로 작성한다. 도구는 쓰지 않는다. 대화에서 확인된 사실만 쓰고, 추정은 "(추정)"으로 표시하며, 모르는 것은 지어내지 않는다. 코드 식별자·경로·명령은 원문 그대로 쓴다. 아래 제목을 그대로 쓰고, 해당 없는 절은 "없음"으로 둔다.
18
19## 목표
20## 완료한 것
21## 결정 사항 (이유 포함)
22## 진행 중인 것 (현재 상태, 멈춘 지점)
23## 다음 단계 (우선순위 순, 체크박스)
24## 관련 파일·명령
25## 미해결 문제·주의사항`
26
27const dir = async ($: EngineInterface) => `${await $.session.root()}/.claude/handoff`
28
29// 한국 시간 기준
30const stamp = async ($: EngineInterface) =>
31  new Date((await $.clock.now()) + 9 * 3_600_000).toISOString().slice(0, 16).replace('T', ' ')
32
33const readOr = async ($: EngineInterface, path: string) => {
34  try {
35    return await $.fs.read(path)
36  } catch {
37    return ''
38  }
39}
40
41export const register: Register = on => {
42  on('session.start', async ($, e, next) => {
43    await $.command.register({
44      name: 'handoff',
45      description: '지금까지의 대화를 인수인계서(.claude/handoff/HANDOFF.md)로 정리한다',
46      argumentHint: '[강조할 내용]',
47    })
48    await $.command.register({
49      name: 'pickup',
50      description: '인수인계서를 읽고 이전 작업을 이어받는다',
51    })
52    await $.command.register({
53      name: 'note',
54      description: '인수인계에 포함할 메모를 직접 남긴다 (.claude/handoff/NOTES.md)',
55      argumentHint: '<메모>',
56    })
57
58    if (e.isInteractive && (await $.fs.exists(`${await dir($)}/HANDOFF.md`))) {
59      $.ui.toast('인수인계서가 있습니다. /pickup 으로 이어받을 수 있습니다.')
60    }
61
62    return next(e)
63  })
64
65  on('prompt.compose', async ($, e, next) => {
66    const composed = await next(e)
67
68    return {
69      sections: [
70        ...composed.sections,
71        { id: 'auto-handoff:rules', text: RULES, scope: 'session' },
72      ],
73    }
74  })
75
76  on('command.run', { command: 'note' }, async ($, e) => {
77    const text = e.args.trim()
78
79    if (text === '') {
80      return { text: '사용법: /note <메모>' }
81    }
82
83    const path = `${await dir($)}/NOTES.md`
84    const before = await readOr($, path)
85    await $.fs.write(path, `${before || '# 수동 메모\n\n'}- ${await stamp($)} ${text}\n`)
86
87    return { text: `메모했습니다: ${text}` }
88  })
89
90  on('command.run', { command: 'handoff' }, async ($, e) => {
91    const base = await dir($)
92    const notes = await readOr($, `${base}/NOTES.md`)
93    const stress = e.args.trim()
94    const reply = await $.model.fork({
95      prompt: [
96        ASK,
97        stress && `특히 다음을 빠뜨리지 않는다: ${stress}`,
98        notes && `사용자가 남긴 수동 메모(그대로 반영):\n${notes}`,
99      ]
100        .filter(Boolean)
101        .join('\n\n'),
102    })
103
104    if (!reply.isAnswered) {
105      return {
106        text:
107          reply.reason === 'nothing-to-fork'
108            ? '아직 정리할 대화가 없습니다.'
109            : `인수인계서를 만들지 못했습니다 (${reply.reason}).`,
110      }
111    }
112
113    const when = await stamp($)
114    const body = `# 인수인계서\n\n작성: ${when} (KST)\n\n${reply.text.trim()}\n`
115    await $.fs.write(`${base}/HANDOFF.md`, body)
116    await $.fs.write(`${base}/archive/${when.replace(/[: ]/g, '-')}.md`, body)
117    await update($, warnedAt, () => 0)
118
119    return {
120      text: `인수인계서를 저장했습니다: .claude/handoff/HANDOFF.md\n새 세션에서 /pickup 으로 이어받으세요.`,
121    }
122  })
123
124  on('command.run', { command: 'pickup' }, async $ => {
125    if (!(await $.fs.exists(`${await dir($)}/HANDOFF.md`))) {
126      return { text: '인수인계서가 없습니다. 이전 세션에서 /handoff 를 먼저 실행하세요.' }
127    }
128
129    void $.prompt.submit({
130      text: '.claude/handoff/HANDOFF.md 를 읽고(있으면 .claude/handoff/NOTES.md 도), 현재 상태를 5줄 이내로 요약한 뒤 "다음 단계"의 첫 항목부터 이어서 진행할지 물어봐. 문서 내용과 실제 파일 상태가 다르면 먼저 알려줘.',
131      asUser: true,
132    })
133
134    return { text: '인수인계서를 읽어 이어받습니다.' }
135  })
136
137  on('turn.complete', async ($, e, next) => {
138    const done = await next(e)
139
140    if (e.agentId === undefined) {
141      const percent = (await $.session.usage()).context.percent ?? 0
142      const last = await read($, warnedAt)
143
144      if (percent >= WARN_AT && percent >= last + STEP) {
145        await update($, warnedAt, () => percent)
146        $.ui.toast(`컨텍스트 ${percent}% 사용. /handoff 로 정리하고 새 세션에서 이어가는 것을 권합니다.`)
147      }
148    }
149
150    return done
151  })
152
153  on('session.compact', async ($, e, next) => {
154    const compacted = await next(e)
155
156    if (e.trigger === 'auto' && e.agentId === undefined) {
157      $.ui.toast('대화가 자동 압축되었습니다. 세부 맥락이 줄었으니 /handoff 를 권합니다.')
158    }
159
160    return compacted
161  }).catch(($, e, next) => next(e))
162}
163

1/** 마지막으로 /handoff 를 권했을 때의 컨텍스트 사용률(%). */
2export type WarnedAt = number
3
4declare module 'claude-code' {
5  interface PluginState {
6    'auto-handoff': { warnedAt: WarnedAt }
7  }
8}
9