context-bar

1// Context Bar: the /context breakdown as a card above the prompt.
2
3import { update } from "claude-code";
4
5const ACCENT = "#d97757";
6// A light grey shows on dark and light backgrounds alike; ink reads on it and on every pastel.
7const FREE = "#c9ced6";
8const INK = "#1f2430";
9const LABEL = { "system tools": "tools", "free space": "free" };
10// /context's own theme keys are mostly greys (several rows share one) and some do not
11// resolve as a background on every surface, so each row gets a fixed colour of its own:
12// mid-lightness pastels, readable on either terminal background.
13const COLOR = {
14  "system prompt": "#5fb3e8",
15  "system tools": "#4fc8a8",
16  "mcp tools": "#a48be8",
17  "custom agents": "#8cc865",
18  agents: "#8cc865",
19  "memory files": "#e8c25a",
20  skills: "#ef8fb5",
21  "slash commands": "#ef8fb5",
22  messages: "#f08a72",
23};
24const SPARE = ["#6fd0d8", "#c69be0", "#f2a96b", "#b5d36a", "#e88f9a"];
25
26// Held by the host, so these survive a hot reload of this file.
27const snapshot = { plugin: "context-bar", key: "snapshot" };
28const collapsed = { plugin: "context-bar", key: "collapsed" };
29const hidden = { plugin: "context-bar", key: "hidden" };
30
31// Mid-turn refresh. Module scope is fine here: a hot reload drops these, and
32// the host cancels the old environment's timer with it, so at worst the next
33// turn writes one extra snapshot.
34const POLL_MS = 2_000;
35const MIN_DELTA = 1_000;
36let poll = null;
37let lastWritten = null;
38
39export function register(on) {
40  on("session.start", async ($, e, next) => {
41    const result = await next(e);
42    await $.command.register({ name: "context-bar", description: "Show or hide the context bar above the prompt" });
43    await takeSnapshot($, true);
44    return result;
45  });
46
47  on("command.run", { command: "context-bar" }, async ($) => {
48    const { value: isHidden = false } = await $.state.get(hidden);
49    await $.state.set(hidden, !isHidden);
50    return { text: isHidden ? "Context bar shown." : "Context bar hidden." };
51  });
52
53  // Fires after each main-thread turn, compaction included: the authoritative
54  // write, in case the throttle below suppressed the turn's final delta.
55  on("session.measure", async ($, e, next) => {
56    const result = await next(e);
57    await takeSnapshot($, true);
58    return result;
59  });
60
61  // Mid-turn refreshes so a long turn's growth shows as it happens: every tool
62  // result lands here, and the poll covers growth with no tool call (long
63  // answers, queued user messages). Subagent turns raise no turn.start; their
64  // tool calls and turn.complete carry an agentId and are left alone.
65  on("turn.start", async ($, e, next) => {
66    const result = await next(e);
67    poll?.cancel();
68    poll = $.clock.every(POLL_MS, () => void takeSnapshot($));
69    return result;
70  });
71
72  on("turn.complete", async ($, e, next) => {
73    const result = await next(e);
74    if (!e.agentId) {
75      poll?.cancel();
76      poll = null;
77    }
78    return result;
79  });
80
81  on("tool.call", async ($, e, next) => {
82    const result = await next(e);
83    if (!e.agentId) await takeSnapshot($);
84    return result;
85  });
86
87  on("ui.render", { component: "AbovePrompt" }, async ($, e, next) => {
88    const { value: snap } = await $.state.get(snapshot);
89    const { value: isHidden = false } = await $.state.get(hidden);
90    if (e.props.hasSurvey || !snap || isHidden) {
91      return next(e);
92    }
93    const { value: isCollapsed = true } = await $.state.get(collapsed);
94    const { Box, Text, Button } = $.ui.resolve(e);
95    const toggle = Button({
96      key: "toggle",
97      label: `${isCollapsed ? "▸" : "▾"} context`,
98      plain: true,
99      onPress: () => update($, collapsed, (v = true) => !v),
100    });
101    return card(Box, Text, toggle, snap, e.props.bodyColumns, isCollapsed);
102  });
103}
104
105// Snapshots the breakdown unless nothing the user can see moved: the whole
106// percentage point unchanged and under MIN_DELTA new tokens. Never throws —
107// a mid-turn usage hiccup must not break the tool call or timer it rides on.
108async function takeSnapshot($, force = false) {
109  try {
110    // `summary` estimates locally: no token-count requests, unlike /context's `full`.
111    const { context } = await $.session.usage({ breakdown: "summary" });
112    const b = context?.breakdown;
113    if (!b?.rawMaxTokens) return;
114    if (
115      !force &&
116      lastWritten &&
117      Math.round(b.percentage) === Math.round(lastWritten.percentage) &&
118      Math.abs(b.totalTokens - lastWritten.totalTokens) < MIN_DELTA
119    ) {
120      return;
121    }
122    lastWritten = { percentage: b.percentage, totalTokens: b.totalTokens };
123    await $.state.set(snapshot, {
124      model: b.model,
125      totalTokens: b.totalTokens,
126      maxTokens: b.rawMaxTokens,
127      percentage: b.percentage,
128      compactAt: b.isAutoCompactEnabled ? b.autoCompactThreshold : undefined,
129      rows: b.categories
130        .filter((c) => c.kind !== "deferred" && c.tokens > 0)
131        .map(({ name, tokens, color, kind }) => ({ name, tokens, color, kind })),
132    });
133  } catch {
134    // See above: stale beats broken.
135  }
136}
137
138function card(Box, Text, toggle, snap, columns, isCollapsed) {
139  const summary = `${short(snap.totalTokens)}`;
140  const detail = ` of ${short(snap.maxTokens)}` + (snap.compactAt ? ` · compacts at ${short(snap.compactAt)}` : "") + " ";
141  const head = Box({
142    flexDirection: "row",
143    justifyContent: "space-between",
144    children: [
145      Box({ flexDirection: "row", children: [Text({ color: ACCENT, children: "◆ " }), toggle] }),
146      Box({
147        flexDirection: "row",
148        children: [
149          Text({ bold: true, children: summary }),
150          Text({ dimColor: true, children: detail }),
151          Text({ backgroundColor: badgeColor(snap.percentage), color: INK, bold: true, children: ` ${snap.percentage}% ` }),
152        ],
153      }),
154    ],
155  });
156  const children = [head];
157  if (!isCollapsed) {
158    children.push(Box({ flexDirection: "row", children: bar(Box, Text, snap, Math.max(10, columns - 6)) }));
159    if (columns >= 60) children.push(legend(Box, Text, snap));
160  }
161  return Box({ flexDirection: "column", borderStyle: "round", borderDimColor: true, paddingX: 1, children });
162}
163
164// Used rows in their colours, the rest of the window grey, a tick where compaction runs.
165// Each segment is a Box `width` cells wide, not a run of characters: the desktop counts
166// columns in its code font but draws Text in a proportional one, so runs of spaces or
167// shade glyphs come out too short or too long there.
168function bar(Box, Text, snap, cells) {
169  const used = snap.rows.filter((r) => r.kind === "used");
170  const counts = allot(used.map((r) => r.tokens), (snap.totalTokens / snap.maxTokens) * cells, cells);
171  const block = (width, backgroundColor, children) => Box({ width, height: 1, flexShrink: 0, backgroundColor, children });
172  const parts = used.map((r, i) => block(counts[i], colorOf(r, i)));
173  const rest = cells - counts.reduce((s, n) => s + n, 0);
174  const tick = snap.compactAt ? Math.round((snap.compactAt / snap.maxTokens) * cells) - (cells - rest) : -1;
175  if (tick >= 0 && tick < rest) {
176    if (tick > 0) parts.push(block(tick, FREE));
177    parts.push(block(1, FREE, Text({ color: INK, bold: true, children: "│" })));
178    if (rest - tick > 1) parts.push(block(rest - tick - 1, FREE));
179  } else if (rest > 0) {
180    parts.push(block(rest, FREE));
181  }
182  return parts;
183}
184
185// Splits about `width` cells among `weights` by largest remainder: one cell each at least, `cells` at most.
186function allot(weights, width, cells) {
187  const target = Math.min(cells, Math.max(Math.round(width), weights.length));
188  const total = weights.reduce((s, w) => s + w, 0) || 1;
189  const shares = weights.map((w) => (w / total) * target);
190  const counts = shares.map((s) => Math.max(1, Math.floor(s)));
191  let left = target - counts.reduce((s, n) => s + n, 0);
192  for (const [, i] of shares.map((s, i) => [s - Math.floor(s), i]).sort((a, b) => b[0] - a[0])) {
193    if (left-- <= 0) break;
194    counts[i]++;
195  }
196  return counts;
197}
198
199function legend(Box, Text, snap) {
200  const items = snap.rows
201    .filter((r) => r.kind !== "buffer")
202    .map((r, i) => {
203      const name = r.name.toLowerCase();
204      const isFree = r.kind === "free";
205      return Text({
206        children: [
207          Text({ color: isFree ? FREE : colorOf(r, i), children: "■ " }),
208          Text({ dimColor: isFree, children: `${LABEL[name] ?? name} ` }),
209          Text({ bold: !isFree, dimColor: isFree, children: short(r.tokens) }),
210          !isFree && Text({ dimColor: true, children: ` ${pct(r.tokens, snap.maxTokens)}` }),
211        ].filter(Boolean),
212      });
213    });
214  return Box({ flexDirection: "row", flexWrap: "wrap", columnGap: 3, children: items });
215}
216
217// `i` is the row's place among the used rows, which come first, so bar and legend agree.
218function colorOf(row, i) {
219  return COLOR[row.name.toLowerCase()] ?? SPARE[i % SPARE.length];
220}
221
222function badgeColor(percent) {
223  if (percent < 50) return "#4fc8a8";
224  if (percent < 80) return "#e8c25a";
225  return "#f06c6c";
226}
227
228function pct(n, of) {
229  return `${Math.round((n / of) * 100)}%`;
230}
231
232function short(n) {
233  if (n >= 1_000_000) return `${+(n / 1_000_000).toFixed(1)}M`;
234  if (n >= 1_000) return `${+(n / 1_000).toFixed(1)}k`;
235  return String(n);
236}
237

1export type ContextBarRow = { name: string; tokens: number; color: string; kind: "used" | "free" | "buffer" };
2
3export type ContextBarSnapshot = {
4  model: string;
5  totalTokens: number;
6  maxTokens: number;
7  percentage: number;
8  compactAt?: number;
9  rows: ContextBarRow[];
10};
11
12declare module "claude-code" {
13  interface PluginState {
14    "context-bar": { snapshot: ContextBarSnapshot; collapsed: boolean; hidden: boolean };
15  }
16}
17