context-keeper

1import { atom, read, update } from 'claude-code'
2import type { ElementTable, EngineInterface, Register, RenderChildren } from 'claude-code'
3
4import type { Checkpoint, ContextSnapshot } from '../types'
5
6// ── claude-mods kit v1 (docs/design.md): identical in every mod ──
7const TONE = { accent: 'claude', ok: 'success', warn: 'warning', bad: 'error', dim: 'inactive' } as const
8const GLYPH = { on: '●', off: '○', warn: '▲', ok: '✓', fail: '✗' } as const
9type Kit = Pick<ElementTable, 'Box' | 'Text'>
10
11/** Pane header: state glyph, mod name, one-line live status. */
12function header({ Box, Text }: Kit, glyph: string, tone: string, name: string, status: string) {
13  return (
14    <Box gap={1}>
15      <Text color={tone}>{glyph}</Text>
16      <Text bold>{name}</Text>
17      <Text dimColor wrap="truncate-end">{status}</Text>
18    </Box>
19  )
20}
21
22/** A section: a dim label (with optional small controls beside it), then its rows. */
23function section({ Box, Text }: Kit, label: string, rows: RenderChildren, aside?: RenderChildren) {
24  return (
25    <Box flexDirection="column">
26      <Box gap={1}>
27        <Text dimColor>{label}</Text>
28        {aside}
29      </Box>
30      {rows}
31    </Box>
32  )
33}
34
35/** A number right-aligned in a fixed-width cell. */
36function num({ Box, Text }: Kit, value: string, width: number, color?: string) {
37  return (
38    <Box width={width} flexShrink={0} justifyContent="flex-end">
39      <Text color={color}>{value}</Text>
40    </Box>
41  )
42}
43
44/** Empty state: what will show up here, and how to get it. */
45function empty({ Text }: Kit, text: string) {
46  return <Text dimColor>{text}</Text>
47}
48// ── end kit ──
49
50const PANE = 'context-keeper'
51const snapshot = atom({ plugin: 'context-keeper', key: 'snapshot' } as const, null)
52const checkpoints = atom({ plugin: 'context-keeper', key: 'checkpoints' } as const, [])
53const busy = atom({ plugin: 'context-keeper', key: 'busy' } as const, null)
54
55const HANDOFF_PROMPT = `Write a compact handoff note for this session so a fresh session can continue with no loss.
56Use these markdown sections, terse bullets, no preamble:
57## Goal
58## Decisions made (and why)
59## Files touched (path: what changed)
60## Current state (what works, what is broken)
61## Open TODOs / next steps
62## Gotchas (things that were tried and failed)`
63
64const TIPS: Record<string, string> = {
65  'MCP tools': 'Disable MCP servers you are not using this session.',
66  'Memory files': 'Trim CLAUDE.md / memory files, or split rarely-needed parts into skills.',
67  'Custom agents': 'Remove agent definitions you never call.',
68  Skills: 'Skills are cheap until loaded; uninstall ones you never use.',
69  Messages: 'Most of the window is conversation: checkpoint, then /compact or /clear.',
70}
71
72/** Rows of the breakdown that are room, not content. */
73const NOT_CONTENT = /^(free space|autocompact buffer)$/i
74
75const bar = (percent: number, width: number) => {
76  const filled = Math.max(0, Math.min(width, Math.round((percent / 100) * width)))
77
78  return '█'.repeat(filled) + '░'.repeat(width - filled)
79}
80
81const k = (n: number) =>
82  n >= 1_000_000 ? `${(n / 1_000_000).toFixed(n % 1_000_000 === 0 ? 0 : 1)}M` : n >= 1000 ? `${(n / 1000).toFixed(1)}k` : String(n)
83
84const stamp = (ms: number) => new Date(ms).toISOString().replace(/[:.]/g, '-').slice(0, 19)
85
86const join = (...parts: string[]) => parts.join('/').replace(/\\/g, '/').replace(/\/+/g, '/')
87
88async function refresh($: EngineInterface): Promise<ContextSnapshot | null> {
89  const usage = await $.session.usage({ breakdown: 'summary' })
90  const ctx = usage.context
91  const breakdown = ctx.breakdown
92  const next: ContextSnapshot = {
93    percent: ctx.percent ?? breakdown?.percentage ?? 0,
94    tokens: ctx.tokens ?? breakdown?.totalTokens ?? 0,
95    window: ctx.window,
96    categories: (breakdown?.categories ?? [])
97      .filter(c => c.tokens > 0 && !c.isDeferred && !NOT_CONTENT.test(c.name))
98      .map(c => ({ name: c.name, tokens: c.tokens }))
99      .sort((a, b) => b.tokens - a.tokens),
100    memoryFiles: (breakdown?.memoryFiles ?? [])
101      .map(f => ({ path: f.path, tokens: f.tokens }))
102      .sort((a, b) => b.tokens - a.tokens)
103      .slice(0, 5),
104    updatedAt: await $.clock.now(),
105  }
106  await update($, snapshot, () => next)
107
108  return next
109}
110
111async function remember($: EngineInterface, cp: Checkpoint) {
112  await update($, checkpoints, list => [cp, ...list].slice(0, 10))
113  const saved = ((await $.store.get('checkpoints')) as Checkpoint[] | undefined) ?? []
114  await $.store.set('checkpoints', [cp, ...saved].slice(0, 30))
115}
116
117/** Asks the model (over the cached transcript) for a handoff note and saves it. */
118async function writeHandoff($: EngineInterface, why: string) {
119  if ((await read($, busy)) !== null) {
120    $.ui.toast('Already writing a checkpoint, one moment…')
121    return
122  }
123  if ((await $.session.turns()) === 0) {
124    $.ui.toast('Nothing to checkpoint yet: a checkpoint summarizes the conversation, and this session has none. Chat first, then try again.', { timeoutMs: 8000 })
125    return
126  }
127  await update($, busy, () => 'Writing handoff note…')
128  $.ui.toast('Writing checkpoint…')
129  try {
130    const result = await $.model.fork({ prompt: HANDOFF_PROMPT })
131    if (!result.isAnswered) {
132      const why: Record<string, string> = {
133        'nothing-to-fork': 'there is no conversation to summarize yet (right after /clear, too)',
134        aborted: 'it was interrupted',
135        'empty-reply': 'the model returned nothing; try again',
136        'api-error': 'the API returned an error; try again in a moment',
137      }
138      $.ui.toast(`Checkpoint not saved: ${why[result.reason] ?? result.reason}.`, { timeoutMs: 8000 })
139      return
140    }
141    const now = await $.clock.now()
142    const percent = (await read($, snapshot))?.percent ?? 0
143    const path = join(await $.session.root(), '.claude', 'checkpoints', `${stamp(now)}-handoff.md`)
144    const header = `<!-- context-keeper handoff · ${why} · context ${Math.round(percent)}% · session ${await $.session.id()} -->\n\n`
145    await $.fs.write(path, header + result.text)
146    await remember($, { path, at: now, percent, kind: 'handoff' })
147    $.ui.toast(`Checkpoint saved: .claude/checkpoints/${stamp(now)}-handoff.md`)
148  } catch (error) {
149    $.ui.toast(`Checkpoint failed: ${String(error).slice(0, 80)}`)
150  } finally {
151    await update($, busy, () => null)
152  }
153}
154
155/** Zero-token archive: dumps the raw conversation text to disk before it is compacted away. */
156async function archive($: EngineInterface, messages: readonly { role: string; text: string; toolUses: readonly { tool: string }[] }[]) {
157  const now = await $.clock.now()
158  const lines = messages.map(m => {
159    const tools = m.toolUses.length > 0 ? `\n_tools: ${m.toolUses.map(t => t.tool).join(', ')}_` : ''
160
161    return `### ${m.role}\n\n${m.text.trim()}${tools}\n`
162  })
163  const path = join(await $.session.root(), '.claude', 'checkpoints', `${stamp(now)}-archive.md`)
164  await $.fs.write(path, `# Transcript archived before compaction\n\n${lines.join('\n')}`)
165  await remember($, { path, at: now, percent: (await read($, snapshot))?.percent ?? 0, kind: 'archive' })
166}
167
168export const register: Register = (on, options) => {
169  const warnAt = Number(options.warnAt ?? 70)
170  const checkpointAt = Number(options.checkpointAt ?? 85)
171  let warned = false
172  let checkpointed = false
173
174  on('session.start', async ($, e, next) => {
175    await $.command.register({ name: 'ctx', description: 'Open the context-keeper panel' })
176    await $.command.register({ name: 'checkpoint', description: 'Save a handoff note of this session to .claude/checkpoints' })
177    await $.command.register({ name: 'resume-checkpoint', description: 'Load the latest checkpoint into the prompt box (use after /clear)' })
178    const saved = ((await $.store.get('checkpoints')) as Checkpoint[] | undefined) ?? []
179    const root = (await $.session.root()).replace(/\\/g, '/')
180    await update($, checkpoints, () => saved.filter(cp => cp.path.startsWith(root)).slice(0, 10))
181
182    return next(e)
183  })
184
185  on('command.run', { command: 'ctx' }, async $ => {
186    await refresh($)
187    await $.ui.open({ id: PANE, title: 'Context' })
188
189    return { text: 'Context panel opened.' }
190  })
191
192  on('command.run', { command: 'checkpoint' }, async $ => {
193    await refresh($)
194    await writeHandoff($, 'manual')
195
196    return { text: 'Checkpoint written (see .claude/checkpoints).' }
197  })
198
199  on('command.run', { command: 'resume-checkpoint' }, async $ => {
200    const latest = (await read($, checkpoints)).find(cp => cp.kind === 'handoff')
201    if (latest === undefined) return { text: 'No checkpoint yet. Run /checkpoint first.' }
202    await $.prompt.fill({ text: `Read ${latest.path} and continue the work from where it left off. Confirm the next step before acting.` })
203
204    return { text: `Prompt box loaded with ${latest.path}` }
205  })
206
207  on('turn.complete', async ($, e, next) => {
208    const result = await next(e)
209    if (e.agentId !== undefined) return result
210    const snap = await refresh($)
211    if (snap === null) return result
212
213    if (snap.percent >= warnAt && !warned) {
214      warned = true
215      const top = snap.categories[0]
216      $.ui.toast(`Context ${Math.round(snap.percent)}% full${top ? ` (biggest: ${top.name} ${k(top.tokens)})` : ''}. /ctx for details.`, { timeoutMs: 8000 })
217    }
218    if (checkpointAt > 0 && snap.percent >= checkpointAt && !checkpointed) {
219      checkpointed = true
220      void writeHandoff($, `auto at ${checkpointAt}%`)
221      void $.prompt.suggest({ text: '/compact' })
222    }
223    $.ui.status(snap.percent >= warnAt ? `ctx ${Math.round(snap.percent)}%` : undefined)
224
225    return result
226  })
227
228  on('session.compact', async ($, e, next) => {
229    if (e.agentId === undefined && e.messages.length > 0) {
230      try {
231        await archive($, e.messages)
232      } catch (error) {
233        $.ui.log(`context-keeper: archive failed: ${String(error)}`, { to: 'debug' })
234      }
235    }
236    const result = await next(e)
237    warned = false
238    checkpointed = false
239    void refresh($)
240
241    return result
242  })
243
244  on('ui.render', { component: 'Pane', requestId: PANE }, async ($, e) => {
245    const els = $.ui.resolve(e)
246    const { Box, Text, Button } = els
247    const Input = 'Input' in els ? els.Input : undefined
248    const snap = await read($, snapshot)
249    const cps = await read($, checkpoints)
250    const working = await read($, busy)
251    const width = Math.max(10, Math.min(40, (e.props.bodyColumns ?? 40) - 12))
252
253    const kit = { Box, Text }
254
255    if (snap === null) {
256      return (
257        <Box flexDirection="column" gap={1}>
258          {header(kit, GLYPH.off, TONE.dim, 'context-keeper', 'no reading yet')}
259          {empty(kit, 'The context reading updates after every turn. Measure now to see what fills the window already.')}
260          <Box>
261            <Button key="refresh" hotkey="r" variant="primary" label="Measure now" onPress={() => void refresh($)} />
262          </Box>
263        </Box>
264      )
265    }
266
267    const pct = Math.round(snap.percent)
268    const tone = snap.percent >= checkpointAt ? TONE.bad : snap.percent >= warnAt ? TONE.warn : TONE.accent
269    const glyph = snap.percent >= warnAt ? GLYPH.warn : GLYPH.on
270    const tips = snap.categories.map(c => TIPS[c.name]).filter((t): t is string => t !== undefined).slice(0, 2)
271
272    return (
273      <Box flexDirection="column" gap={1}>
274        <Box flexDirection="column">
275          {header(kit, glyph, tone, 'context-keeper', `${pct}% full · ${k(Math.max(0, snap.window - snap.tokens))} left`)}
276          <Text color={tone}>{bar(snap.percent, width)}</Text>
277          <Text dimColor wrap="truncate-end">
278            {k(snap.tokens)} of {k(snap.window)} tokens
279          </Text>
280        </Box>
281
282        {section(
283          kit,
284          'What fills it',
285          <Box flexDirection="column">
286            {snap.categories.length === 0 && empty(kit, 'No breakdown yet. It fills in after the first turn.')}
287            {snap.categories.slice(0, 7).map(c => (
288              <Box gap={1}>
289                <Box flexGrow={1} flexShrink={1}>
290                  <Text wrap="truncate-end">{c.name}</Text>
291                </Box>
292                {num(kit, k(c.tokens), 7)}
293                <Text dimColor>{bar((c.tokens / Math.max(1, snap.window)) * 100, 12)}</Text>
294              </Box>
295            ))}
296            {snap.memoryFiles.length > 0 && (
297              <Text dimColor wrap="truncate-end">
298                Largest memory file: {snap.memoryFiles[0]?.path.split(/[\/]/).at(-1)} ({k(snap.memoryFiles[0]?.tokens ?? 0)})
299              </Text>
300            )}
301          </Box>,
302        )}
303
304        {tips.length > 0 &&
305          section(
306            kit,
307            'Tips',
308            tips.map(t => <Text dimColor>• {t}</Text>),
309          )}
310
311        {section(
312          kit,
313          'Actions',
314          <Box flexDirection="column">
315            {working !== null && <Text color={TONE.accent}>{GLYPH.on} {working}</Text>}
316            <Box gap={1} flexWrap="wrap">
317              <Button key="checkpoint" hotkey="c" variant="primary" label="Checkpoint" onPress={() => void writeHandoff($, 'manual')} />
318              <Button key="compact" hotkey="k" label="Checkpoint + compact" onPress={() => void writeHandoff($, 'before compact').then(() => $.command.run({ command: 'compact' }))} />
319              <Button key="refresh" hotkey="r" label="Refresh" onPress={() => void refresh($)} />
320            </Box>
321            {Input !== undefined && (
322              <Input
323                key="focus"
324                label="Compact, keeping:"
325                placeholder="e.g. the auth refactor and failing tests"
326                submitLabel="Compact"
327                onSubmit={(value: string) => void $.command.run({ command: 'compact', args: value })}
328              />
329            )}
330          </Box>,
331        )}
332
333        {section(
334          kit,
335          'Checkpoints',
336          <Box flexDirection="column">
337            {cps.length === 0 && empty(kit, 'None yet. A checkpoint is a handoff note (goal, decisions, files, TODOs) you can reload after /clear.')}
338            {cps.slice(0, 4).map((cp, i) => (
339              <Box gap={1}>
340                <Text color={TONE.ok}>{GLYPH.ok}</Text>
341                <Text dimColor wrap="truncate-end">
342                  {new Date(cp.at).toLocaleTimeString()} {cp.kind} at {Math.round(cp.percent)}%
343                </Text>
344                <Button
345                  key={`load-${i}`}
346                  plain
347                  label="load"
348                  onPress={() => void $.prompt.fill({ text: `Read ${cp.path} and continue the work from where it left off. Confirm the next step before acting.` })}
349                />
350              </Box>
351            ))}
352          </Box>,
353        )}
354      </Box>
355    )
356  })
357}
358

1export type ContextSnapshot = {
2  percent: number
3  tokens: number
4  window: number
5  categories: { name: string; tokens: number }[]
6  memoryFiles: { path: string; tokens: number }[]
7  updatedAt: number
8}
9
10export type Checkpoint = { path: string; at: number; percent: number; kind: 'handoff' | 'archive' }
11
12declare module 'claude-code' {
13  interface PluginState {
14    'context-keeper': {
15      snapshot: ContextSnapshot | null
16      checkpoints: Checkpoint[]
17      busy: string | null
18    }
19  }
20}
21