context-bar

1// Context Bar: what is filling my context window?
2//   Above the prompt, the window as one stacked bar, a color per category, with a legend of
3//   tokens and shares and where auto-compaction runs. The categories are /context's own
4//   (system, tools, mcp, memory, skills, messages, free space), the long names shortened.
5//   It refreshes after each turn. /context-bar shows or hides it, and the choice is kept
6//   across sessions.
7import { atom, read, update } from 'claude-code'
8import type { EngineInterface, Register } from 'claude-code'
9
10import type { Reading, Slice } from '../types'
11
12const MIN_WIDTH = 20 // narrower than this, the bar is not drawn
13const SPLIT = '   '
14// /context's theme gives several rows the same grey, so each used row gets its own color, in order.
15const PALETTE = ['#7aa2f7', '#7dcfff', '#bb9af7', '#9ece6a', '#e0af68', '#f7768e', '#73daca', '#ff9e64', '#c0caf5']
16const MESSAGES = '#d97757' // the row that grows, in the accent color
17const FREE = '#808080' // a mid grey thin line reads as empty on dark and light themes alike
18const BUFFER = '#808080'
19const GLYPH = { used: '█', free: '─', buffer: '░' } as const
20// /context spells these rows out in full; the legend line is short of room, so the long ones go by
21// a shorter name. Anything not named here keeps the name the engine gave it.
22const LABELS: Record<string, string> = {
23  'system prompt': 'system',
24  'system tools': 'tools',
25  'mcp server instructions': 'mcp',
26  'memory files': 'memory',
27}
28export const label = (name: string) => LABELS[name] ?? name
29
30// Held by the host, so the bar survives a hot reload of this file.
31const reading = atom({ plugin: 'context-bar', key: 'reading' } as const, null as Reading | null)
32const isHidden = atom({ plugin: 'context-bar', key: 'isHidden' } as const, false)
33
34export const register: Register = on => {
35  on('session.start', async ($, e, next) => {
36    const r = await next(e)
37    await $.command.register({ name: 'context-bar', description: 'Show or hide the context window bar above the prompt' }).catch(() => {}) // a name Claude Code already has is refused: start anyway
38    const hidden = (await $.store.get('isHidden').catch(() => undefined)) === true
39    await update($, isHidden, () => hidden)
40    void refresh($).catch(() => {})
41    return r
42  })
43
44  on('turn.complete', async ($, e, next) => {
45    const r = await next(e)
46    if (!e.agentId) await refresh($).catch(() => {}) // a subagent's turn fills its own window, not this one
47    return r
48  })
49
50  on('session.compact', async ($, e, next) => {
51    const r = await next(e)
52    if (!e.agentId && 'messages' in r) void refresh($).catch(() => {}) // a /compact empties the window without a turn ending
53    return r
54  })
55
56  on('command.run', { command: 'context-bar' }, async $ => {
57    const hidden = await update($, isHidden, h => !h)
58    await $.store.set('isHidden', hidden).catch(() => {})
59    if (!hidden) await refresh($).catch(() => {})
60    return { text: hidden ? 'Context bar hidden. /context-bar shows it again' : 'Context bar on' }
61  })
62
63  on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
64    const rest = await next(e) // what other mods and Claude Code draw here stays
65    const r = await read($, reading)
66    if (e.props.hasSurvey || (await read($, isHidden)) || !r) return rest
67    const { Box, Text } = $.ui.resolve(e)
68    const inner = e.props.bodyColumns - 4 // the border and padding take 4 cells
69    if (inner < MIN_WIDTH) return rest
70
71    const head = `${tokens(r.total)} of ${tokens(r.window)}${r.compactsAt ? ` · compacts at ${tokens(r.compactsAt)}` : ''}`
72    const pct = ` ${r.percent}% `
73    const level = r.compactsAt ? r.total / r.compactsAt : r.total / r.window
74    return (
75      <Box flexDirection="column">
76        <Box flexDirection="column" borderStyle="round" borderColor="inactive" paddingX={1}>
77          <Box flexDirection="row" justifyContent="space-between">
78            <Text wrap="truncate-end">
79              <Text color="#d97757">{'◆ '}</Text>
80              <Text bold>context</Text>
81            </Text>
82            <Text wrap="truncate-start">
83              <Text dimColor>{`${head} `}</Text>
84              <Text bold color="black" backgroundColor={level >= 0.9 ? 'red' : level >= 0.7 ? 'yellow' : 'green'}>{pct}</Text>
85            </Text>
86          </Box>
87          <Text>
88            {cells(r, inner).map(c => (
89              <Text color={c.color}>{c.text}</Text>
90            ))}
91          </Text>
92          {legend(r, inner).map(line => (
93            <Text wrap="truncate-end">
94              {line.map((s, i) => (
95                <Text>
96                  {i > 0 && <Text>{SPLIT}</Text>}
97                  <Text color={s.color}>{s.kind === 'used' ? '■ ' : `${GLYPH[s.kind]} `}</Text>
98                  <Text dimColor={s.kind !== 'used'}>{`${label(s.name)} `}</Text>
99                  <Text bold={s.kind === 'used'}>{tokens(s.tokens)}</Text>
100                  {s.kind === 'used' && <Text dimColor>{` ${share(s.tokens, r.window)}`}</Text>}
101                </Text>
102              ))}
103            </Text>
104          ))}
105        </Box>
106        {rest}
107      </Box>
108    )
109  })
110}
111
112// Asks the engine for /context's breakdown, estimated locally (no token-count calls).
113async function refresh($: EngineInterface) {
114  if (await read($, isHidden)) return
115  const usage = await $.session.usage({ breakdown: 'summary' })
116  const b = usage.context.breakdown
117  if (!b || !(b.rawMaxTokens > 0)) return // no window to measure against
118  await update($, reading, () => toReading(b))
119}
120
121export function toReading(b: {
122  categories: { name: string; tokens: number; color: string; kind: string }[]
123  totalTokens: number
124  rawMaxTokens: number
125  percentage: number
126  autoCompactThreshold?: number
127  isAutoCompactEnabled: boolean
128}): Reading {
129  const slices: Slice[] = b.categories
130    .filter(c => c.kind !== 'deferred' && c.tokens > 0)
131    .map(c => ({ name: c.name.toLowerCase(), tokens: c.tokens, color: c.color, kind: c.kind as Slice['kind'] }))
132  const order = { used: 0, free: 1, buffer: 2 }
133  slices.sort((x, y) => order[x.kind] - order[y.kind]) // stable: used rows keep /context's order
134  let next = 0
135  for (const s of slices) {
136    s.color = s.kind === 'free' ? FREE : s.kind === 'buffer' ? BUFFER : s.name === 'messages' ? MESSAGES : PALETTE[next++ % PALETTE.length]!
137  }
138  return {
139    slices,
140    total: b.totalTokens,
141    window: b.rawMaxTokens,
142    percent: b.percentage,
143    compactsAt: b.isAutoCompactEnabled ? b.autoCompactThreshold : undefined,
144  }
145}
146
147// The bar as runs of cells: each slice gets its share of `width`, a used one at least one cell.
148export function cells(r: Reading, width: number) {
149  const sizes = r.slices.map(s => Math.max(s.kind === 'used' ? 1 : 0, Math.round((s.tokens / r.window) * width)))
150  // Rounding leaves the sum a few cells off: free space takes the difference first, then the largest slices.
151  let diff = width - sizes.reduce((a, n) => a + n, 0)
152  const isUsed = (i: number) => r.slices[i]!.kind === 'used'
153  const order = r.slices.map((_, i) => i).sort((a, b) => Number(isUsed(a)) - Number(isUsed(b)) || sizes[b]! - sizes[a]!)
154  for (const i of order) {
155    if (diff === 0) break
156    const size = Math.max(isUsed(i) ? 1 : 0, sizes[i]! + diff)
157    diff -= size - sizes[i]!
158    sizes[i] = size
159  }
160  return r.slices.map((s, i) => ({ color: s.color, kind: s.kind, text: GLYPH[s.kind].repeat(sizes[i]!) })).filter(c => c.text !== '')
161}
162
163// The legend, packed into lines no wider than `width`.
164export function legend(r: Reading, width: number) {
165  const lines: Slice[][] = [[]]
166  let used = 0
167  for (const s of r.slices) {
168    const size = 2 + label(s.name).length + 1 + tokens(s.tokens).length + (s.kind === 'used' ? 1 + share(s.tokens, r.window).length : 0)
169    const line = lines.at(-1)!
170    if (line.length > 0 && used + SPLIT.length + size > width) {
171      lines.push([s])
172      used = size
173    } else {
174      used += (line.length > 0 ? SPLIT.length : 0) + size
175      line.push(s)
176    }
177  }
178  return lines.filter(l => l.length > 0)
179}
180
181export function tokens(n: number) {
182  if (n >= 1_000_000) return `${+(n / 1_000_000).toFixed(n % 1_000_000 === 0 ? 0 : 1)}M`
183  if (n >= 10_000) return `${Math.round(n / 1000)}k`
184  if (n >= 1000) return `${+(n / 1000).toFixed(1)}k`
185  return String(n)
186}
187
188export function share(n: number, window: number) {
189  const p = (n / window) * 100
190  if (p > 0 && p < 0.1) return '<0.1%'
191  return `${p >= 10 ? Math.round(p) : +p.toFixed(1)}%`
192}
193

1export type Slice = { name: string; tokens: number; color: string; kind: 'used' | 'free' | 'buffer' }
2
3export type Reading = {
4  slices: Slice[]
5  total: number // tokens in use
6  window: number // the window measured against
7  percent: number
8  compactsAt?: number // where auto-compaction runs, when it is on
9}
10
11declare module 'claude-code' {
12  interface PluginState {
13    'context-bar': { reading: Reading | null; isHidden: boolean }
14  }
15}
16