context-meter

1import { atom, read, update } from 'claude-code'
2import type { Register } from 'claude-code'
3
4import { bar, cacheTtl, cacheView, fade, legend, tokens, toReading, withOverride } from './meter'
5
6const reading = atom({ plugin: 'context-meter', key: 'reading' } as const, null)
7const cache = atom({ plugin: 'context-meter', key: 'cache' } as const, { lastAt: null })
8// The clock the cache line was last drawn at; written only when that line's text would change.
9const now = atom({ plugin: 'context-meter', key: 'now' } as const, 0)
10const onSubscription = atom({ plugin: 'context-meter', key: 'onSubscription' } as const, false)
11const notice = atom({ plugin: 'context-meter', key: 'notice' } as const, null)
12// The band shows only when asked: `/context-meter` flips it, `/context-meter on` or `off` sets it, for this session;
13// until then the `band` option decides. Hiding it changes the drawing only: the window is still measured and the
14// cache clock still runs, so the band is current the moment it comes back.
15const shown = atom({ plugin: 'context-meter', key: 'shown' } as const, null)
16const SWITCH: Record<string, boolean> = { on: true, off: false }
17
18async function isShown($: any, band: unknown): Promise<boolean> {
19  return (await read($, shown)) ?? band === 'on'
20}
21
22type Detail = 'summary' | 'full'
23
24async function ttlFor($: any, option: unknown) {
25  return cacheTtl(typeof option === 'string' ? option : undefined, await read($, onSubscription))
26}
27
28// The breakdown /context draws, read again after each turn. `summary` estimates locally and sends nothing.
29async function measure($: any, detail: Detail): Promise<void> {
30  const usage = await $.session.usage({ breakdown: detail, columns: 80 })
31  // Rate-limit windows come back only on a subscription: the one hint there is about the cache's lifetime.
32  await update($, onSubscription, () => usage.rateLimits.length > 0)
33  const pct = await $.env.get('CLAUDE_AUTOCOMPACT_PCT_OVERRIDE').catch(() => undefined)
34  await update($, reading, () => withOverride(toReading(usage.context), pct))
35}
36
37// How long after a compaction the band reads the window again: the engine puts the summary in place of the
38// conversation only once every session.compact hook has returned, so a reading taken inside the hook (or
39// as the call resolves) still counts the old messages.
40const SETTLE_MS = 1000
41// A compaction whose new window the band has not read yet; the turn that ran /compact reads it as it ends.
42let isPending = false
43
44// The main conversation's cache is rewritten by the compaction's next request, so its clock starts over.
45async function compacted($: any, detail: Detail): Promise<void> {
46  await update($, cache, () => ({ lastAt: null }))
47  isPending = true
48  $.clock.after(SETTLE_MS, () => void remeasure($, detail))
49}
50
51async function remeasure($: any, detail: Detail): Promise<void> {
52  isPending = false
53  await measure($, detail).catch(() => undefined)
54}
55
56// Moves the drawn clock on, but only when the cache line's text would change, so the band redraws once a
57// second while the countdown runs and once a minute after it has run out.
58async function tick($: any, option: unknown): Promise<void> {
59  const [stamp, at, t, r] = [await read($, cache), await $.clock.now(), await ttlFor($, option), await read($, reading)]
60  const before = cacheView(stamp.lastAt, await read($, now), t.ttl, t.why, r?.tokens ?? null).text
61  if (cacheView(stamp.lastAt, at, t.ttl, t.why, r?.tokens ?? null).text !== before) await update($, now, () => at)
62}
63
64// Restarts the cache clock at `at`, the moment a request that used the cache was sent.
65async function stamp($: any, at: number): Promise<void> {
66  const drawnAt = await $.clock.now()
67  await update($, cache, () => ({ lastAt: at }))
68  await update($, now, () => drawnAt)
69}
70
71const reason = (err: unknown) => (err instanceof Error ? err.message : String(err))
72
73// The band's button: the same compaction /compact runs. It is refused while a turn runs or with too few
74// messages, and a hook may veto it. The outcome shows in the band as well as a toast, which some surfaces hide.
75// An SDK host (the desktop app's Code tab, the IDE extensions) has no between-turns compaction yet: there
76// /compact runs as a command inside a turn, so the button runs that command, as if it were typed, and the
77// session.compact hook below re-reads the window when it lands.
78async function compactNow($: any, detail: Detail, surface: string): Promise<void> {
79  await update($, notice, () => 'compacting… (the model is writing the summary)')
80  let said: string | null = null
81  const viaCommand = async () => {
82    try {
83      await $.command.run({ command: 'compact', args: '' })
84    } catch (err) {
85      said = `could not compact now: ${reason(err)}`
86    }
87  }
88  if (surface !== 'terminal') {
89    await viaCommand()
90  } else {
91    try {
92      const result = await $.session.compact()
93      if (result.skip !== undefined) said = `compaction skipped: ${result.skip}`
94      else await compacted($, detail)
95    } catch (err) {
96      if (/headless/i.test(reason(err))) await viaCommand()
97      else said = `could not compact now: ${reason(err)}`
98    }
99  }
100  await update($, notice, () => said)
101  if (said !== null) $.ui.toast(`context-meter: ${said}`)
102}
103
104export const register: Register = (on, options) => {
105  const detail: Detail = options.breakdown === 'full' ? 'full' : 'summary'
106  // session.start can fire again in one load (an enable, a worker respawn); one ticking clock is enough.
107  let ticking: { cancel: () => void } | undefined
108
109  on('session.start', async ($, e, next) => {
110    const started = await next(e)
111    // `immediate`: a switch for the band works while Claude is still working.
112    await $.command
113      .register({ name: 'context-meter', description: 'Show or hide the context and cache band', argumentHint: '[on|off]', immediate: true })
114      .catch(() => undefined)
115    await measure($, detail).catch(() => undefined)
116    ticking?.cancel()
117    ticking = $.clock.every(1000, () => void tick($, options.cacheTtl).catch(() => undefined))
118    return started
119  })
120
121  on('command.run', { command: 'context-meter' }, async ($, e) => {
122    const word = e.args.trim().toLowerCase()
123    const show = SWITCH[word] ?? (word === '' ? !(await isShown($, options.band)) : undefined)
124    if (show === undefined) return { text: 'use /context-meter, /context-meter on or /context-meter off' }
125    await update($, shown, () => show)
126    return { text: show ? 'band on (/context-meter off hides it)' : 'band off (/context-meter on shows it)' }
127  })
128
129  on('session.measure', async ($, e, next) => {
130    const measured = await next(e)
131    await measure($, detail).catch(() => undefined)
132    return measured
133  })
134
135  // Every request of the main conversation reads or writes its cache, and each one that hits it resets the
136  // cache's timer. So the clock restarts at each model request (each step of a turn, not only the turn's end),
137  // from the moment it was sent; a request that brought back no usage (failed, interrupted) did not count.
138  // A subagent's requests have caches of their own.
139  on('turn.step', async function* ($, e, next) {
140    const sentAt = await $.clock.now()
141    const response = yield* next(e)
142    if (e.agentId === undefined && response.usage !== null) await stamp($, sentAt).catch(() => undefined)
143    return response
144  })
145
146  on('turn.complete', async ($, e, next) => {
147    const done = await next(e)
148    if (e.agentId === undefined) {
149      await update($, notice, () => null).catch(() => undefined)
150      if (isPending) await remeasure($, detail)
151    }
152    return done
153  })
154
155  // /compact and auto-compaction; the band's own button calls compact() and sees its answer there instead.
156  on('session.compact', async ($, e, next) => {
157    const result = await next(e)
158    // An observer: the compaction's result goes back as it came, whatever happens to the band.
159    if (e.agentId === undefined && e.trigger !== 'precompute' && result.skip === undefined) await compacted($, detail).catch(() => undefined)
160    return result
161  })
162
163  on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
164    const below = await next(e)
165    if (!(await isShown($, options.band))) return below
166    const r = await read($, reading)
167    if (e.props.hasSurvey || r === null || r.window <= 0) return below
168    const { Box, Button, Text } = $.ui.resolve(e)
169    const t = await ttlFor($, options.cacheTtl)
170    // While a turn runs, each of its requests resets the timer, so the countdown only means something between
171    // turns: then it runs from the last request.
172    const idle = cacheView((await read($, cache)).lastAt, await read($, now), t.ttl, t.why, r.tokens)
173    const view = e.props.isWorking
174      ? { state: 'warm' as const, left: 1, text: `cache ▸ kept warm while Claude works: each request resets the ${t.ttl} timer` }
175      : idle
176    const width = Math.max(10, Math.min(60, e.props.bodyColumns - 2))
177    const head = [
178      `context ▸ ${r.used !== null ? tokens(r.used) : '?'} of ${tokens(r.window)}`,
179      r.percent !== null ? `${r.percent}%` : null,
180      r.compactsAt === null
181        ? 'auto-compact off'
182        : `compacts at ${tokens(r.compactsAt)}${r.compactsWhy !== null ? ` (${r.compactsWhy})` : ''}`,
183    ].filter(Boolean).join(' · ')
184    const columns = Math.max(20, e.props.bodyColumns - 2)
185    const rows = legend(r, columns)
186    // The whole band when there is room, else the two rows that matter: the fill and the cache clock.
187    const isFull = e.props.maxRows >= 6 + rows.length
188    const said = await read($, notice)
189    // Nothing to compact before the live window's first response (a new or just-compacted conversation),
190    // and a compaction is refused while a turn runs: the button shows only when one can work.
191    const canCompact = !e.props.isWorking && r.tokens !== null && said?.startsWith('compacting') !== true
192    return (
193      <Box flexDirection="column">
194        <Box justifyContent="space-between" width={columns}>
195          <Text wrap="truncate">{`${head} `}</Text>
196          {canCompact && <Button key="compact" label="Compact" hotkey="c" onPress={() => compactNow($, detail, e.surface)} />}
197        </Box>
198        {isFull && (
199          <Box>
200            {bar(r, width).map((run, i) => (
201              <Text key={`run-${i}`} color={run.color ?? undefined} dimColor={run.color === null}>
202                {(run.color === null ? '░' : '█').repeat(run.cells)}
203              </Text>
204            ))}
205          </Box>
206        )}
207        {isFull &&
208          rows.map((row, i) => (
209            <Box key={`legend-${i}`}>
210              {row.map((item, k) => (
211                <Box key={item.name}>
212                  <Text color={item.color ?? undefined} dimColor={item.color === null}>{`${k > 0 ? '   ' : ''}■ `}</Text>
213                  <Text>{`${item.name} `}</Text>
214                  <Text bold>{item.tokens}</Text>
215                  <Text dimColor>{` ${item.share}`}</Text>
216                </Box>
217              ))}
218            </Box>
219          ))}
220        <Text wrap="truncate" color={view.state === 'warm' ? fade(view.left) : view.state === 'expired' ? 'error' : undefined} dimColor={view.state === 'none'}>
221          {view.text}
222        </Text>
223        {said !== null && <Text color={said.startsWith('compacting') ? 'warning' : 'error'} wrap="truncate">{`context-meter: ${said}`}</Text>}
224        {below}
225      </Box>
226    )
227  })
228}
229

1// Pure helpers for context-meter: token labels, the category bar, the cache clock and its colour.
2
3import type { CacheTtl, Category, ContextReading } from '../types'
4
5const MINUTE = 60_000
6export const TTL_MS: Record<CacheTtl, number> = { '5m': 5 * MINUTE, '1h': 60 * MINUTE }
7
8// 4.2k, 17k, 1M: the way /context writes token counts.
9export function tokens(n: number): string {
10  if (n >= 1_000_000) return `${trim(n / 1_000_000)}M`
11  if (n >= 1_000) return `${n >= 10_000 ? Math.round(n / 1_000) : trim(n / 1_000)}k`
12  return String(Math.round(n))
13}
14
15function trim(x: number): string {
16  return x.toFixed(1).replace(/\.0$/, '')
17}
18
19// The breakdown as the band draws it: the categories that fill the window, in /context's order and colours.
20export function toReading(context: any): ContextReading {
21  const b = context?.breakdown
22  const categories: Category[] = (b?.categories ?? [])
23    .filter((c: any) => c.kind === 'used' && c.tokens > 0)
24    .map((c: any) => ({ name: String(c.name).toLowerCase(), tokens: c.tokens, color: c.color }))
25  return {
26    tokens: context?.tokens ?? null,
27    window: b?.rawMaxTokens ?? context?.window ?? 0,
28    percent: b?.percentage ?? context?.percent ?? null,
29    used: b?.totalTokens ?? context?.tokens ?? null,
30    compactsAt: b?.isAutoCompactEnabled ? (b.autoCompactThreshold ?? null) : null,
31    compactsWhy: null,
32    categories,
33  }
34}
35
36// CLAUDE_AUTOCOMPACT_PCT_OVERRIDE (1-100) moves auto-compaction to that share of the auto-compact window; it
37// can only lower the threshold. The breakdown's threshold need not include it (on 2.1.294 a 1M session set to
38// 50 still reports 967k), so the band takes the lower of the two, marked as the person's setting when it is
39// the override. Where the breakdown already includes it, its own lower figure wins and nothing is marked.
40export function withOverride(reading: ContextReading, pct: string | undefined): ContextReading {
41  const n = Number(pct)
42  if (reading.compactsAt === null || !Number.isInteger(n) || n < 1 || n > 100) return reading
43  const at = Math.floor((reading.window * n) / 100)
44  return at < reading.compactsAt ? { ...reading, compactsAt: at, compactsWhy: `your ${n}% setting` } : reading
45}
46
47// One bar `width` cells wide: a run of cells per category, in proportion to the window, then the free part.
48// A category too small for a cell still gets one, so nothing that fills the window disappears from the bar.
49export function bar(reading: ContextReading, width: number): { cells: number; color: string | null }[] {
50  if (reading.window <= 0 || width <= 0) return []
51  const runs = reading.categories.map(c => ({ cells: Math.max(1, Math.round((c.tokens / reading.window) * width)), color: c.color }))
52  let used = runs.reduce((sum, r) => sum + r.cells, 0)
53  // Rounding up the small ones can overrun; take the excess back from the largest runs.
54  while (used > width) {
55    const largest = runs.reduce((a, b) => (b.cells > a.cells ? b : a))
56    if (largest.cells <= 1) break
57    largest.cells -= 1
58    used -= 1
59  }
60  return used < width ? [...runs, { cells: width - used, color: null }] : runs
61}
62
63export type LegendItem = { name: string; tokens: string; share: string; color: string | null }
64
65// One entry per category plus the free part, laid out in rows no wider than `columns` cells, so every one shows.
66export function legend(reading: ContextReading, columns: number): LegendItem[][] {
67  const share = (n: number) => {
68    const p = (n / Math.max(1, reading.window)) * 100
69    return p > 0 && p < 1 ? '<1%' : `${Math.round(p)}%`
70  }
71  const items: LegendItem[] = reading.categories.map(c => ({ name: c.name, tokens: tokens(c.tokens), share: share(c.tokens), color: c.color }))
72  if (reading.used !== null && reading.window > reading.used) {
73    const free = reading.window - reading.used
74    items.push({ name: 'free', tokens: tokens(free), share: share(free), color: null })
75  }
76  // An entry draws as "■ name 4.2k 1%", entries three cells apart.
77  const width = (i: LegendItem) => 2 + i.name.length + 1 + i.tokens.length + 1 + i.share.length
78  const rows: LegendItem[][] = []
79  let row: LegendItem[] = []
80  let used = 0
81  for (const item of items) {
82    const gap = row.length > 0 ? 3 : 0
83    if (row.length > 0 && used + gap + width(item) > columns) {
84      rows.push(row)
85      row = []
86      used = 0
87    }
88    used += (row.length > 0 ? 3 : 0) + width(item)
89    row.push(item)
90  }
91  if (row.length > 0) rows.push(row)
92  return rows
93}
94
95// The cache's lifetime: the option when it names one; otherwise one hour on a subscription (Claude Code's
96// default there, within the plan's included usage) and five minutes with an API key or a cloud provider.
97export function cacheTtl(option: string | undefined, onSubscription: boolean): { ttl: CacheTtl; why: string } {
98  if (option === '5m' || option === '1h') return { ttl: option, why: 'set in options' }
99  return onSubscription ? { ttl: '1h', why: 'assumed: subscription' } : { ttl: '5m', why: 'assumed: API key' }
100}
101
102export type CacheView = { state: 'none' | 'warm' | 'expired'; text: string; left: number }
103
104// What the cache line says, `now` milliseconds into the session's clock.
105export function cacheView(lastAt: number | null, now: number, ttl: CacheTtl, why: string, contextTokens: number | null): CacheView {
106  const life = TTL_MS[ttl]
107  if (lastAt === null) return { state: 'none', text: `cache ▸ starts with the next message (${ttl} TTL, ${why})`, left: 1 }
108  const remaining = lastAt + life - now
109  if (remaining > 0) return { state: 'warm', text: `cache ▸ ${clock(remaining)} left (${ttl} TTL, ${why})`, left: remaining / life }
110  const resend = contextTokens !== null ? `: the next message writes ${tokens(contextTokens)} to the cache again` : ''
111  return { state: 'expired', text: `cache ▸ expired ${ago(-remaining)} ago${resend}`, left: 0 }
112}
113
114// 52:07, or 4:05 under an hour's last ten minutes; never a fraction of a second.
115export function clock(ms: number): string {
116  const s = Math.ceil(ms / 1000)
117  const h = Math.floor(s / 3600)
118  const m = Math.floor((s % 3600) / 60)
119  const sec = String(s % 60).padStart(2, '0')
120  return h > 0 ? `${h}:${String(m).padStart(2, '0')}:${sec}` : `${m}:${sec}`
121}
122
123function ago(ms: number): string {
124  const m = Math.floor(ms / MINUTE)
125  return m < 1 ? `${Math.floor(ms / 1000)} s` : m < 120 ? `${m} min` : `${Math.floor(m / 60)} h`
126}
127
128// Green with the whole lifetime left, through amber, to red as it runs out: `left` is the share remaining.
129export function fade(left: number): string {
130  const red = [220, 38, 38]
131  const amber = [217, 119, 6]
132  const green = [22, 163, 74]
133  const x = Math.min(1, Math.max(0, left))
134  // Two straight runs: red to amber over the last half, amber to green over the first.
135  const [from, to, t] = x <= 0.5 ? [red, amber, x / 0.5] : [amber, green, (x - 0.5) / 0.5]
136  return `#${from.map((v, k) => Math.round(v + ((to[k] ?? v) - v) * t).toString(16).padStart(2, '0')).join('')}`
137}
138

1export type CacheTtl = '5m' | '1h'
2
3// One row of /context's breakdown that fills the window (free space and the compaction buffer are left out).
4export type Category = { name: string; tokens: number; color: string }
5
6export type ContextReading = {
7  // Input tokens the last response was answered over; null before the first response of the live window.
8  tokens: number | null
9  // The window the breakdown measures against (the compaction window when that is smaller).
10  window: number
11  percent: number | null
12  // The breakdown's estimated total; null without a breakdown.
13  used: number | null
14  // The token count at which auto-compaction runs; null when it is off.
15  compactsAt: number | null
16  // Where compactsAt came from when it is not Claude Code's own figure (the person's percentage override).
17  compactsWhy: string | null
18  categories: Category[]
19}
20
21// When the main conversation's last model response arrived, by the session's clock; null before one, or
22// after a compaction, whose next request writes a new cache.
23export type CacheStamp = { lastAt: number | null }
24
25declare module 'claude-code' {
26  interface PluginState {
27    // notice: what the Compact button last did ("compacting…", or why it could not), until the next turn ends.
28    // shown: the band switched on or off with /context-meter this session; null until then (the band option decides).
29    'context-meter': { reading: ContextReading | null; cache: CacheStamp; now: number; onSubscription: boolean; notice: string | null; shown: boolean | null }
30  }
31}
32