auto-compact

1import type { EngineInterface, Register, Timer } from 'claude-code'
2
3// Idle minutes after the main loop's last API request before auto-compacting.
4// The API offers a five-minute and a one-hour cache lifetime, and the one-hour
5// one is the longer-lived cache: compacting a little ahead of an hour of
6// inactivity lets the summarization request re-read the cheap cache instead of
7// reprocessing the full history, and 55 minutes leaves a small margin under
8// that hour. Set AUTO_COMPACT_IDLE_MIN to change it.
9const DEFAULT_IDLE_MIN = 55
10
11// Model names that count as running on Anthropic. A custom endpoint or gateway
12// can forward requests anywhere; compacting a conversation that runs on
13// another provider buys nothing, so a custom endpoint only arms when the
14// current model name looks like a Claude model. Set AUTO_COMPACT_PAID_MODELS
15// to a different regex to widen or narrow this.
16const DEFAULT_PAID_MODELS = 'claude|opus|sonnet|fable|haiku'
17
18let eligible = false
19let isCompacting = false
20let timer: Timer | undefined
21
22function disarm() {
23  timer?.cancel()
24  timer = undefined
25}
26
27// Env and timing are read once at session start, so arming the clock stays a
28// plain synchronous call.
29let cache: { minutes: number; idleMs: number; paidModels: RegExp } | undefined
30
31async function load($: EngineInterface) {
32  const min = Number(await $.env.get('AUTO_COMPACT_IDLE_MIN'))
33  const src = (await $.env.get('AUTO_COMPACT_PAID_MODELS')) ?? DEFAULT_PAID_MODELS
34  let paidModels: RegExp
35  try {
36    paidModels = new RegExp(src, 'i')
37  } catch {
38    paidModels = new RegExp(DEFAULT_PAID_MODELS, 'i')
39  }
40  const minutes = min > 0 ? min : DEFAULT_IDLE_MIN
41  return { minutes, idleMs: minutes * 60_000, paidModels }
42}
43
44// The result of each attempt is written to ~/.claude/state/auto-compact/<sessionId>.json
45// so a status line script can show when the conversation was last compacted
46// (several windows may be open at once, hence one file per session). The file
47// holds the most recent auto-compact that actually ran: while no compact has
48// run yet, a skipped or failed attempt is recorded, and afterwards a later
49// skip or failure leaves the last good record in place, so the display does
50// not blink to nothing. A write that fails never affects the compact itself.
51async function record($: EngineInterface, status: 'ok' | 'skip' | 'fail', detail?: string) {
52  try {
53    const home = (await $.env.get('USERPROFILE')) ?? (await $.env.get('HOME'))
54    if (!home) return
55    const id = await $.session.id()
56    const at = await $.clock.now()
57    const path = `${home.replace(/\\/g, '/')}/.claude/state/auto-compact/${id}.json`
58    if (status !== 'ok') {
59      // Keep the last good record: a skip or a failure is not an auto-compact,
60      // and failures are already surfaced in a toast, so nothing is swallowed.
61      try {
62        const prior = JSON.parse((await $.fs.read(path)) as string) as { at?: unknown; status?: unknown }
63        if (prior && prior.status === 'ok' && prior.at) return
64      } catch {
65        // No record yet - write this one.
66      }
67    }
68    await $.fs.write(path, JSON.stringify({ at, status, detail: detail ?? null }))
69  } catch {
70    // The status line only displays; a failed read or write is not worth blocking on.
71  }
72}
73
74function arm($: EngineInterface) {
75  if (!cache) return
76  timer = $.clock.after(cache.idleMs, async () => {
77    timer = undefined
78    const baseUrl = (await $.env.get('ANTHROPIC_BASE_URL')) ?? ''
79    const isDirect = baseUrl === '' || baseUrl.includes('api.anthropic.com')
80    if (!cache) return
81    if (!isDirect && !cache.paidModels.test(await $.session.model())) return
82    isCompacting = true
83    try {
84      $.ui.toast(`Idle ${cache.minutes} min: auto-compacting while the prompt cache is still warm...`)
85      const done = await $.session.compact()
86      $.ui.toast('skip' in done ? `Auto-compact skipped: ${done.skip}` : 'Auto-compact complete')
87      await record($, 'skip' in done ? 'skip' : 'ok', 'skip' in done ? String(done.skip) : undefined)
88    } catch (err) {
89      // A turn was already running (compact is refused while a turn runs):
90      // that turn itself renews the cache. Any other reason is reported too,
91      // not quietly swallowed.
92      const msg = err instanceof Error ? err.message : String(err)
93      $.ui.toast(`Auto-compact did not run: ${msg}`)
94      await record($, 'fail', msg)
95    } finally {
96      isCompacting = false
97    }
98  })
99}
100
101export const register: Register = on => {
102  eligible = false
103  isCompacting = false
104  cache = undefined
105  disarm()
106
107  on('session.start', async ($, e, next) => {
108    const result = await next(e)
109    // Only sessions a person is watching get toasts; scheduled or headless
110    // runs are left alone.
111    eligible = e.isInteractive
112    cache = await load($)
113    disarm()
114    return result
115  })
116
117  // The clock restarts at every main-loop API request (typed input, a subagent
118  // report waking the main agent, a scheduled wake-up - all count), because
119  // the cache is renewed by requests, not by typing. A subagent's own requests
120  // don't count: those renew the subagent's own cache.
121  on('turn.step', async function* ($, e, next) {
122    if (e.agentId !== undefined || !eligible || isCompacting) return yield* next(e)
123    disarm()
124    try {
125      return yield* next(e)
126    } finally {
127      arm($)
128    }
129  })
130}
131