ctx-keeper

1// ctx-keeper: a band above the prompt with the prompt-cache countdown, context
2// size, cache rewrite cost, 5h/week limits and session cost (cache-keeper's
3// pills), plus Irfan's hand-off flow. When context passes 350k and nothing is
4// still running (no turn, no open tasks, no subagents), it runs /re-fresh,
5// copies the hand-off to the clipboard (and saves it), compacts, then sends the
6// hand-off back with "do nothing, reply ready".
7
8import { atom, read, update } from 'claude-code'
9import type { EngineInterface, Register, RenderElement } from 'claude-code'
10
11import type { Meter, Phase } from '../types'
12
13const THRESHOLD = 350_000
14const CACHE_MIN = 60 // settings.json promptCacheTtl "1h" (main chat); subagents stay 5m
15const WARN_MIN = 1
16const COOLDOWN_MS = 10 * 60_000
17// Auto keep-warm: from Irfan's idle gaps, pinging pays off up to ~20m; past that a rewrite is cheaper.
18// ponytail: with a 1h cache this never fires inside the 20m window; raise AUTO_WARM_MAX_MIN (~180) to bridge 1-3h breaks
19const PING_AT_MIN = CACHE_MIN - 1
20const AUTO_WARM_MAX_MIN = 20
21const LIMIT_STOP_PCT = 90
22
23const meter = atom({ plugin: 'ctx-keeper', key: 'meter' } as const, {
24  tokens: 0,
25  fiveHour: null,
26  week: null,
27  usd: null,
28  lastTurnAt: 0,
29} as Meter)
30const phase = atom({ plugin: 'ctx-keeper', key: 'phase' } as const, 'idle' as Phase)
31const autoWarm = atom({ plugin: 'ctx-keeper', key: 'autoWarm' } as const, true as boolean)
32
33const REFRESH_ARGS =
34  'full Goal: continue the current work in this same chat right after compaction. Stays here, nothing travels.'
35
36// ponytail: 1h cache-write price per Mtok (2x input) by model family; edit if pricing changes
37function usdPerMtok(model: string): number {
38  if (/haiku/i.test(model)) return 2
39  if (/sonnet/i.test(model)) return 6
40  return 10
41}
42
43function fmtK(n: number): string {
44  return n >= 1000 ? `${Math.round(n / 1000)}k` : String(n)
45}
46
47function extractHandoff(answer: string): string {
48  const blocks = [...answer.matchAll(/```[a-z]*\n([\s\S]*?)```/g)].map(m => (m[1] ?? "").trim())
49  const longest = blocks.sort((a, b) => b.length - a.length)[0]
50  return longest !== undefined && longest.length > 200 ? longest : answer.trim()
51}
52
53// Module state: a hot reload resets it, which only forgets open tasks.
54const openTasks = new Set<string>()
55let isTurnRunning = false
56let lastAnswerOk = true
57let lastFlowAt = 0
58let pendingHandoff: string | null = null
59let warnedFor = 0
60let lastHumanAt = Date.now() // end of the last human turn; starts at load so a reload cannot ping forever
61let pingInFlight = false
62
63function autoWarmBlock(m: Meter, now: number): string | null {
64  if (m.fiveHour !== null && m.fiveHour >= LIMIT_STOP_PCT) return `5h ≥${LIMIT_STOP_PCT}%`
65  if (lastHumanAt > 0 && now - lastHumanAt >= AUTO_WARM_MAX_MIN * 60_000) return `idle ${AUTO_WARM_MAX_MIN}m+`
66  return null
67}
68
69function ping($: EngineInterface): void {
70  pingInFlight = true
71  void $.prompt.submit({ text: 'Cache keep-warm ping. Reply with only: ok' })
72}
73
74async function startFlow($: EngineInterface): Promise<void> {
75  if ((await read($, phase)) !== 'idle') return
76  lastFlowAt = await $.clock.now()
77  await update($, phase, () => 'refresh')
78  $.ui.toast('ctx-keeper: writing the hand-off with /re-fresh')
79  try {
80    await $.command.run({ command: 're-fresh', args: REFRESH_ARGS })
81  } catch (error) {
82    $.ui.toast(`ctx-keeper: /re-fresh failed: ${String(error)}`)
83    await update($, phase, () => 'idle')
84  }
85}
86
87async function finishFlow($: EngineInterface, answer: string): Promise<void> {
88  const handoff = extractHandoff(answer)
89  if (handoff.length < 100) {
90    $.ui.toast('ctx-keeper: /re-fresh gave no hand-off, stopped before compacting')
91    await update($, phase, () => 'idle')
92    return
93  }
94
95  // pbcopy is the Mac clipboard and works from the desktop app too; ui.copy is the fallback.
96  const pb = await $.process.run(['pbcopy'], { stdin: handoff, timeoutMs: 5000 }).catch(() => null)
97  const copied = pb?.exitCode === 0 ? { isCopied: true } : await $.ui.copy({ text: handoff })
98  const home = (await $.env.get('HOME')) ?? ''
99  const dir = `${home}/.claude/mods-data/ctx-keeper/handoffs`
100  const stamp = new Date(await $.clock.now()).toISOString().replace(/[:T]/g, '-').slice(0, 16)
101  await $.process.run(['mkdir', '-p', dir])
102  await $.fs.write(`${dir}/${stamp}.md`, handoff)
103  $.ui.toast(
104    `ctx-keeper: hand-off ${copied.isCopied ? 'copied' : 'not copied'} and saved to ${dir}/${stamp}.md. Compacting.`,
105  )
106
107  // Same path as typing /compact; the session.compact hook below sends the paste.
108  pendingHandoff = handoff
109  await update($, phase, () => 'compact')
110  await $.command.run({
111    command: 'compact',
112    args: 'A hand-off prompt is sent right after this. Keep the current task state and file paths.',
113  })
114}
115
116async function paste($: EngineInterface): Promise<void> {
117  const handoff = pendingHandoff
118  pendingHandoff = null
119  if (handoff === null) return void (await update($, phase, () => 'idle'))
120  await update($, phase, () => 'paste')
121  await $.prompt.submit({
122    text:
123      'Hand-off from before compaction is below. Read it and do nothing else: no tools, no work. ' +
124      'Reply with only the word: ready\n\n' +
125      handoff,
126  })
127}
128
129// The size is measured AFTER turn.complete, so the check runs on each measure
130// and after each turn, once nothing is running.
131async function maybeStart($: EngineInterface): Promise<void> {
132  if (isTurnRunning || !lastAnswerOk || openTasks.size > 0) return
133  if ((await read($, phase)) !== 'idle') return
134  const m = await read($, meter)
135  if (m.tokens < THRESHOLD || (await $.clock.now()) - lastFlowAt <= COOLDOWN_MS) return
136  const agents = await $.agent.list().catch(() => [])
137  if (agents.some(a => /run|pend|start|active/i.test(a.status))) return
138  $.clock.after(0, () => void startFlow($))
139}
140
141export const register: Register = on => {
142  on('session.compact', async ($, e, next) => {
143    const result = await next(e)
144    if ((await read($, phase)) !== 'compact') return result
145    if (result.skip !== undefined) {
146      pendingHandoff = null
147      $.ui.toast(`ctx-keeper: compact skipped (${result.skip}); hand-off is on the clipboard`)
148      await update($, phase, () => 'idle')
149    } else {
150      $.clock.after(0, () => void paste($))
151    }
152    return result
153  })
154
155  on('turn.start', async ($, e, next) => {
156    isTurnRunning = true
157    return next(e)
158  })
159
160  on('session.start', async ($, e, next) => {
161    // A reload kills any flow in flight, but $.state keeps its phase: reset it.
162    await update($, phase, () => 'idle')
163    // Every 30s: redraw, auto-ping before the cache goes cold, else warn.
164    $.clock.every(30_000, () => {
165      void (async () => {
166        $.ui.invalidate('ui.render')
167        const m = await read($, meter)
168        if (m.lastTurnAt === 0) return
169        const now = await $.clock.now()
170        const idleMin = (now - m.lastTurnAt) / 60_000
171        const left = CACHE_MIN - idleMin
172        const canPing =
173          (await read($, autoWarm)) &&
174          !isTurnRunning &&
175          !pingInFlight &&
176          (await read($, phase)) === 'idle' &&
177          autoWarmBlock(m, now) === null
178        if (canPing && left > 0 && idleMin >= PING_AT_MIN) return ping($)
179        if (!canPing && left > 0 && left <= WARN_MIN && warnedFor !== m.lastTurnAt) {
180          warnedFor = m.lastTurnAt
181          $.ui.toast(`ctx-keeper: cache goes cold in ${Math.ceil(left)}m.`)
182        }
183      })()
184    })
185    return next(e)
186  })
187
188  on('session.measure', async ($, e, next) => {
189    const five = e.rateLimits.find(r => r.kind === 'five_hour')
190    const week = e.rateLimits.find(r => r.kind === 'seven_day')
191    await update($, meter, m => ({
192      ...m,
193      tokens: e.context.tokens ?? m.tokens,
194      fiveHour: five?.percentUsed ?? m.fiveHour,
195      week: week?.percentUsed ?? m.week,
196      usd: e.cost?.usd ?? m.usd,
197    }))
198    void maybeStart($)
199    return next(e)
200  })
201
202  // Open tasks: a hand-off waits until the task list is clear.
203  // Task tools are not in every build, so the matchers are patterns.
204  on('tool.call', { tool: /^TaskCreate$/ }, async ($, e, next) => {
205    const ran = await next(e)
206    const id = /#?(\d+)/.exec(ran.text ?? '')?.[1]
207    if (id !== undefined) openTasks.add(id)
208    return ran
209  })
210  on('tool.call', { tool: /^TaskUpdate$/ }, async ($, e, next) => {
211    const input = e as unknown as { taskId?: string; status?: string }
212    if (input.taskId !== undefined && (input.status === 'completed' || input.status === 'deleted')) {
213      openTasks.delete(String(input.taskId))
214    }
215    return next(e)
216  })
217
218  on('turn.complete', async ($, e, next) => {
219    const result = await next(e)
220    if (e.agentId !== undefined) return result
221    isTurnRunning = false
222    lastAnswerOk = e.reason === 'answer'
223
224    const now = await $.clock.now()
225    await update($, meter, m => ({ ...m, lastTurnAt: now }))
226    if (!pingInFlight) lastHumanAt = now
227    pingInFlight = false
228    const current = await read($, phase)
229
230    if (current === 'refresh') {
231      const answer = e.answer
232      $.clock.after(0, () => void finishFlow($, answer))
233      return result
234    }
235    if (current === 'paste') {
236      await update($, phase, () => 'idle')
237      $.ui.toast('ctx-keeper: hand-off pasted, Claude is waiting for you')
238      return result
239    }
240
241    void maybeStart($)
242    return result
243  })
244
245  on('ui.render', { component: 'AbovePrompt' }, async ($, e, next): Promise<RenderElement> => {
246    const below = await next(e)
247    if (e.props.hasSurvey) return below
248    const { Box, Text, Button } = $.ui.resolve(e)
249    const m = await read($, meter)
250    const current = await read($, phase)
251    const now = await $.clock.now()
252    const model = await $.session.model()
253    const isAutoOn = await read($, autoWarm)
254
255    const leftMin = m.lastTurnAt === 0 ? null : Math.round(CACHE_MIN - (now - m.lastTurnAt) / 60_000)
256    const isWarm = leftMin !== null && leftMin > 0
257    const cacheColor = !isWarm ? 'red' : leftMin <= WARN_MIN ? 'yellow' : 'green'
258    const ctxColor = m.tokens >= THRESHOLD ? 'red' : m.tokens >= THRESHOLD * 0.8 ? 'yellow' : 'green'
259    const rewriteUsd = (m.tokens / 1_000_000) * usdPerMtok(model)
260    const warmUsd = rewriteUsd / 20 // cache read is 0.1x input, 1h write is 2x
261    const limits = [
262      m.fiveHour === null ? null : `5h ${Math.round(m.fiveHour)}%`,
263    ]
264      .filter(Boolean)
265      .join(' · ')
266
267    return (
268      <Box flexDirection="column">
269        <Box flexWrap="wrap" marginY={1}>
270          <Text color={cacheColor}>● </Text>
271          <Text dimColor>
272            {leftMin === null ? 'cache n/a' : isWarm ? `cache warm ${leftMin}m` : 'cache cold'}
273            {' | '}
274          </Text>
275          <Text color={ctxColor}>ctx {fmtK(m.tokens)}/{fmtK(THRESHOLD)}</Text>
276          <Text dimColor>
277            {' | '}${rewriteUsd.toFixed(2)} | ${warmUsd.toFixed(2)}
278            {limits === '' ? '' : ` | ${limits}`}
279          </Text>
280          {isAutoOn && isWarm && autoWarmBlock(m, now) !== null && (
281            <Text color="yellow"> | auto-warm off ({autoWarmBlock(m, now)})</Text>
282          )}
283          {current !== 'idle' && <Text color="red"> ● {current}</Text>}
284          {!e.props.isWorking && current === 'idle' && <Text>   </Text>}
285          {!e.props.isWorking && current === 'idle' && (
286            <Button key="auto" plain hotkey="w" label={`auto-warm: ${isAutoOn ? 'on' : 'off'}`} onPress={() => {
287              void update($, autoWarm, v => !v).then(() => $.ui.invalidate('ui.render'))
288            }} />
289          )}
290          {!e.props.isWorking && current === 'idle' && <Text>   </Text>}
291          {!e.props.isWorking && current === 'idle' && (
292            <Button key="compact" plain hotkey="c" label="compact" onPress={() => {
293              void $.command.run({ command: 'compact', args: '' }).catch(err => $.ui.toast(`ctx-keeper: compact failed: ${String(err)}`))
294            }} />
295          )}
296          {!e.props.isWorking && current === 'idle' && <Text>   </Text>}
297          {!e.props.isWorking && current === 'idle' && (
298            <Button key="handoff" plain hotkey="h" label="hand-off now" onPress={() => {
299              void startFlow($)
300            }} />
301          )}
302        </Box>
303        {below}
304      </Box>
305    )
306  })
307}
308

1export type Meter = {
2  tokens: number
3  fiveHour: number | null
4  week: number | null
5  usd: number | null
6  lastTurnAt: number
7}
8
9export type Phase = 'idle' | 'refresh' | 'compact' | 'paste'
10
11declare module 'claude-code' {
12  interface PluginState {
13    'ctx-keeper': { meter: Meter; phase: Phase; autoWarm: boolean }
14  }
15}
16