context-gauge

1import type { EngineInterface as Engine, Register } from 'claude-code'
2
3// context-gauge:
4//   9. a status-line gauge of the context window (percent, tokens, compactions
5//      so far), toasts as it crosses 70% and 85%, and a band row from 80% with
6//      a "Compact now" button. At each compaction it tells the summarizer what
7//      was in flight, logs that snapshot, and hands it back to Claude with the
8//      next prompt. /context-log lists the compactions of this session.
9
10const LOG = 'c:'
11const WARN_AT = 80
12const TOAST_AT = [70, 85]
13
14type Compaction = {
15  ts: number
16  trigger: string
17  percent: number | null
18  tokensBefore: number | null
19  tokensAfter: number | null
20  snapshot: string
21}
22
23let sessionId = ''
24let percent: number | null = null
25let tokens: number | null = null
26let windowSize: number | null = null
27let toasted = new Set<number>()
28let compactions: Compaction[] = []
29let reinject: string | null = null
30
31// What the session is in the middle of, gathered from its own events
32let task = ''
33let lastPrompt = ''
34const edited: string[] = []
35const actions: string[] = []
36const links = new Set<string>()
37
38const HUMAN = new Set(['composer', 'bridge', 'sdk'])
39
40const short = (s: string, n: number) => {
41  const one = s.replace(/\s+/g, ' ').trim()
42  return one.length > n ? one.slice(0, n - 1) + '…' : one
43}
44const k = (n: number) => (n >= 1000 ? `${Math.round(n / 1000)}k` : String(n))
45const hhmm = (ts: number) => new Date(ts).toTimeString().slice(0, 5)
46
47function snapshot(): string {
48  const lines = [`Task: ${task || '(unknown)'}`]
49  if (lastPrompt && lastPrompt !== task) lines.push(`Latest request: ${lastPrompt}`)
50  if (edited.length) lines.push(`Files edited: ${edited.slice(-12).join(', ')}`)
51  if (links.size) lines.push(`PRs/links in play: ${[...links].slice(-5).join(', ')}`)
52  if (actions.length) lines.push(`Last actions: ${actions.slice(-8).join(' | ')}`)
53  return lines.join('\n')
54}
55
56async function measure($: Engine) {
57  try {
58    const u = await $.session.usage()
59    percent = typeof u.context.percent === 'number' ? Math.round(u.context.percent) : null
60    tokens = u.context.tokens ?? null
61    windowSize = u.context.window
62  } catch {
63    return
64  }
65  const bits: string[] = []
66  if (percent !== null) bits.push(`ctx ${percent}%`)
67  if (tokens !== null && windowSize) bits.push(`${k(tokens)}/${k(windowSize)}`)
68  if (compactions.length) bits.push(`compacted ${compactions.length}×`)
69  $.ui.status(bits.length ? bits.join(' · ') : undefined)
70
71  if (percent !== null) {
72    for (const t of TOAST_AT) {
73      if (percent >= t && !toasted.has(t)) {
74        toasted.add(t)
75        $.ui.toast(
76          t >= 85
77            ? `Context at ${percent}%: compaction is close. /compact now keeps the in-flight work in the summary.`
78            : `Context at ${percent}%`,
79          { timeoutMs: t >= 85 ? 12_000 : 6000 },
80        )
81      }
82    }
83  }
84  $.ui.invalidate('ui.render')
85}
86
87async function persist($: Engine) {
88  if (sessionId) await $.store.set(LOG + sessionId, compactions)
89}
90
91export const register: Register = on => {
92  on('session.start', async ($, e, next) => {
93    sessionId = await $.session.id()
94    compactions = ((await $.store.get(LOG + sessionId)) as Compaction[] | undefined) ?? []
95    // Drop logs of sessions untouched for a week
96    const now = await $.clock.now()
97    for (const key of await $.store.keys()) {
98      if (!key.startsWith(LOG) || key === LOG + sessionId) continue
99      const list = (await $.store.get(key)) as Compaction[] | undefined
100      const last = list?.[list.length - 1]?.ts ?? 0
101      if (now - last > 7 * 24 * 60 * 60_000) await $.store.delete(key)
102    }
103    // A resumed session starts a new process: recover the task from the transcript
104    if (!task) {
105      try {
106        const msgs = await $.session.messages()
107        const human = msgs.filter(m => m.role === 'user' && m.text && !m.text.startsWith('<'))
108        if (human[0]) task = short(human[0].text, 120)
109        const latest = human[human.length - 1]
110        if (latest) lastPrompt = short(latest.text, 160)
111      } catch {
112        // no transcript yet
113      }
114    }
115    await $.command.register({
116      name: 'context-log',
117      description: 'Context fill now, and what was in flight at each compaction this session',
118    })
119    void measure($)
120    return next(e)
121  })
122
123  on('command.run', { command: 'context-log' }, async $ => {
124    await measure($)
125    const head = `Context: ${percent ?? '?'}%${tokens !== null && windowSize ? ` (${k(tokens)} of ${k(windowSize)})` : ''} · ${compactions.length} compaction${compactions.length === 1 ? '' : 's'} this session`
126    const body = compactions.map(
127      (c, i) =>
128        `#${i + 1} ${hhmm(c.ts)} ${c.trigger}${c.percent !== null ? ` at ${c.percent}%` : ''}${c.tokensBefore && c.tokensAfter ? ` (${k(c.tokensBefore)} → ${k(c.tokensAfter)})` : ''}\n${c.snapshot.replace(/^/gm, '    ')}`,
129    )
130    return { text: [head, ...body].join('\n\n') }
131  })
132
133  on('session.measure', async ($, e, next) => {
134    if (e.changed.includes('context')) void measure($)
135    return next(e)
136  })
137
138  on('prompt.submit', async ($, e, next) => {
139    const kind = e.origin?.kind
140    if ((!kind || HUMAN.has(kind)) && !e.text.startsWith('<')) {
141      if (!task) task = short(e.text, 120)
142      lastPrompt = short(e.text, 160)
143    }
144    if (reinject) {
145      const text = reinject
146      reinject = null
147      return next({
148        ...e,
149        context: [...(e.context ?? []), `[context-gauge] Just before the last compaction, this session was:\n${text}`],
150      })
151    }
152    return next(e)
153  })
154
155  on('tool.call', async ($, e, next) => {
156    const ran = await next(e)
157    if (e.agentId !== undefined) return ran
158    const call = e as unknown as { tool: string } & Record<string, unknown>
159    const fp = (call.file_path ?? call.notebook_path) as string | undefined
160    if (['Edit', 'Write', 'NotebookEdit', 'MultiEdit'].includes(call.tool) && typeof fp === 'string') {
161      const name = fp.replace(/^\/Users\/[^/]+/, '~')
162      const i = edited.indexOf(name)
163      if (i >= 0) edited.splice(i, 1)
164      edited.push(name)
165      if (edited.length > 30) edited.shift()
166    }
167    const what =
168      call.tool === 'Bash' && typeof call.command === 'string'
169        ? `$ ${short(call.command, 60)}`
170        : typeof fp === 'string'
171          ? `${call.tool} ${fp.split('/').pop()}`
172          : call.tool.startsWith('mcp__')
173            ? (call.tool.split('__').pop() ?? call.tool)
174            : call.tool
175    actions.push(`${what}${ran.isError ? ' (failed)' : ''}`)
176    if (actions.length > 20) actions.shift()
177    for (const m of (ran.text ?? '').matchAll(/https:\/\/github\.com\/[\w.-]+\/[\w.-]+\/pull\/\d+/g)) links.add(m[0])
178    return ran
179  })
180
181  on('turn.complete', async ($, e, next) => {
182    const r = await next(e)
183    if (e.agentId === undefined) void measure($)
184    return r
185  })
186
187  on('session.compact', async ($, e, next) => {
188    if (e.agentId !== undefined || e.trigger === 'precompute') return next(e)
189    const snap = snapshot()
190    const before = percent
191    // Ask the summarizer to keep the in-flight state
192    const keep = `Preserve exactly, as its own section: the in-flight work below, plus any open PR numbers, branch and worktree names, pending questions to the user, and decisions not yet acted on.\n${snap}`
193    const result = await next({ ...e, instructions: e.instructions ? `${e.instructions}\n\n${keep}` : keep })
194    if ('skip' in result && result.skip !== undefined) return result
195
196    const entry: Compaction = {
197      ts: await $.clock.now(),
198      trigger: e.trigger,
199      percent: before,
200      tokensBefore: result.tokensBefore ?? null,
201      tokensAfter: result.tokensAfter ?? null,
202      snapshot: snap,
203    }
204    compactions.push(entry)
205    compactions = compactions.slice(-20)
206    await persist($)
207    reinject = snap
208    toasted = new Set()
209    $.ui.log(
210      `Compaction #${compactions.length} (${e.trigger}${before !== null ? ` at ${before}%` : ''}). In flight: ${short(task || lastPrompt || 'unknown', 80)}${edited.length ? ` · ${edited.length} files edited` : ''}. /context-log for the full snapshot.`,
211    )
212    void measure($)
213    return result
214  })
215
216  // Band row once the window is nearly full
217  on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
218    const below = await next(e)
219    if (e.props.hasSurvey || percent === null || percent < WARN_AT) return below
220    const { Box, Text, Button } = $.ui.resolve(e)
221    return (
222      <Box flexDirection="column">
223        <Box gap={1}>
224          <Text color={percent >= 90 ? 'red' : 'yellow'}>
225            ◔ Context {percent}%{tokens !== null && windowSize ? ` (${k(tokens)}/${k(windowSize)})` : ''}: compaction is near
226          </Text>
227          <Button
228            key="compact-now"
229            label="Compact now"
230            plain
231            onPress={async () => {
232              await $.session.compact({
233                instructions: `Preserve exactly, as its own section, the in-flight work:\n${snapshot()}`,
234              })
235            }}
236          />
237        </Box>
238        {below}
239      </Box>
240    )
241  })
242}
243