context-meter

1import { atom, read, update } from "claude-code";
2import type {
3  EngineInterface,
4  Register,
5  SessionCompactResult,
6  SessionContextUsage,
7} from "claude-code";
8
9import type { Reading } from "../types";
10
11const reading = atom({ plugin: "context-meter", key: "reading" } as const, null);
12const compacted = atom({ plugin: "context-meter", key: "compacted" } as const, null);
13const isCompacting = atom({ plugin: "context-meter", key: "isCompacting" } as const, false);
14
15// Desktop meter size in CSS pixels; terminal meter width in cells.
16const BAR_WIDTH = 160;
17const BAR_HEIGHT = 6;
18const BAR_CELLS = 24;
19
20// A desktop cell is 8 CSS px. The native header row's text sits 5 px further
21// in than the band's own inset, so 0.625 lines "Context" up with it.
22const DESKTOP_INSET = 0.625;
23
24// Quality drops with the absolute token count, so the zones are fixed sizes.
25const AMBER_FROM = 200_000;
26const RED_FROM = 350_000;
27
28const zoneColor = (tokens: number) => {
29  if (tokens >= RED_FROM) return "#d2553f";
30  if (tokens >= AMBER_FROM) return "#e2a33a";
31
32  return "#6ba368";
33};
34
35const meterSvg = (percent: number, color: string) => {
36  const r = BAR_HEIGHT / 2;
37  const fill = percent <= 0 ? 0 : Math.max(BAR_HEIGHT, (Math.min(100, percent) / 100) * BAR_WIDTH);
38
39  return [
40    `<svg xmlns="http://www.w3.org/2000/svg" width="${BAR_WIDTH}" height="${BAR_HEIGHT}" viewBox="0 0 ${BAR_WIDTH} ${BAR_HEIGHT}">`,
41    `<rect width="${BAR_WIDTH}" height="${BAR_HEIGHT}" rx="${r}" fill="#8a8a8a" fill-opacity="0.22"/>`,
42    fill > 0
43      ? `<rect width="${fill.toFixed(1)}" height="${BAR_HEIGHT}" rx="${r}" fill="${color}"/>`
44      : "",
45    `</svg>`,
46  ].join("");
47};
48
49const toReading = (context: SessionContextUsage): Reading => ({
50  tokens: context.tokens ?? null,
51  window: context.window,
52  percent: context.percent ?? null,
53});
54
55const size = (tokens: number | null) => {
56  if (tokens === null) return "?";
57
58  // Rounded first, so 999,700 reads "1.0M", not "1000k".
59  const thousands = Math.round(tokens / 1000);
60
61  if (thousands >= 1000) return `${(tokens / 1_000_000).toFixed(1)}M`;
62
63  return `${thousands}k`;
64};
65
66const record = async ($: EngineInterface, result: SessionCompactResult) => {
67  if (result.skip !== undefined) return;
68
69  await update($, compacted, () => ({
70    before: result.tokensBefore ?? null,
71    after: result.tokensAfter ?? null,
72  }));
73};
74
75// Runs `/compact` as if typed, queued until the session is idle.
76// `$.session.compact()` is refused in SDK-hosted sessions such as the
77// desktop's, where compaction runs inside a turn. The `session.compact` hook
78// below shows "Compacting…" only once it runs, so a mid-turn press toasts instead.
79// `run` resolves once the command has run, so presses until then queue nothing more.
80let isQueued = false;
81
82const compact = async ($: EngineInterface) => {
83  if (isQueued) return;
84
85  isQueued = true;
86
87  try {
88    await $.command.run({ command: "compact" });
89  } catch (error) {
90    $.ui.toast(`Compaction failed: ${error instanceof Error ? error.message : String(error)}`);
91  } finally {
92    isQueued = false;
93  }
94};
95
96export const register: Register = (on) => {
97  // A reload keeps `$.state` but drops a compaction in flight, so start clean.
98  on("session.start", async ($, e, next) => {
99    const { context } = await $.session.usage();
100    await Promise.all([
101      update($, reading, () => toReading(context)),
102      update($, compacted, () => null),
103      update($, isCompacting, () => false),
104    ]);
105
106    return next(e);
107  });
108
109  on("session.measure", async ($, e, next) => {
110    if (e.changed.includes("context")) {
111      await update($, reading, () => toReading(e.context));
112
113      // A reply ends the compacted note; skip the write when there is none.
114      if (e.context.tokens !== undefined && (await read($, compacted)) !== null) {
115        await update($, compacted, () => null);
116      }
117    }
118
119    return next(e);
120  });
121
122  // `/compact` and auto-compaction of the main conversation.
123  on("session.compact", async ($, e, next) => {
124    const isMain = e.agentId === undefined && e.trigger !== "precompute";
125
126    if (!isMain) return next(e);
127
128    await update($, isCompacting, () => true);
129
130    try {
131      const result = await next(e);
132      await record($, result);
133
134      return result;
135    } finally {
136      await update($, isCompacting, () => false);
137    }
138  });
139
140  on("ui.render", { component: "AbovePrompt" }, async ($, e, next) => {
141    if (e.props.hasSurvey || e.props.view.agentId !== undefined) return next(e);
142
143    const [now, last, isBusy] = await Promise.all([
144      read($, reading),
145      read($, compacted),
146      read($, isCompacting),
147    ]);
148
149    if (now === null) return next(e);
150
151    const ui = $.ui.resolve(e);
152    const { Box, Button, Text } = ui;
153    const Svg = "Svg" in ui ? ui.Svg : undefined;
154
155    const meter = [];
156
157    if (last !== null) {
158      meter.push(
159        <Text dimColor>
160          {`Compacted ${size(last.before)} → ${size(last.after)} · the meter returns after the next reply`}
161        </Text>,
162      );
163    } else if (now.tokens === null || now.percent === null) {
164      meter.push(<Text dimColor>{`Context · no reply yet · ${size(now.window)} window`}</Text>);
165    } else {
166      const percent = now.percent;
167      const color = zoneColor(now.tokens);
168      meter.push(<Text dimColor>Context</Text>);
169
170      if (Svg !== undefined) {
171        meter.push(
172          <Svg
173            source={meterSvg(percent, color)}
174            alt={`${percent}% of the context window used`}
175            width={BAR_WIDTH}
176            height={BAR_HEIGHT}
177          />,
178        );
179      } else {
180        const filled = Math.round((Math.min(100, percent) / 100) * BAR_CELLS);
181
182        meter.push(
183          <Box>
184            <Text color={color}>{"━".repeat(filled)}</Text>
185            <Text dimColor>{"━".repeat(BAR_CELLS - filled)}</Text>
186          </Box>,
187        );
188      }
189
190      meter.push(
191        <Text bold color={color}>{`${percent}%`}</Text>,
192        <Text dimColor>{`${size(now.tokens)} / ${size(now.window)}`}</Text>,
193      );
194    }
195
196    // Tokens are unknown until a reply, so a resumed session is told apart from
197    // a fresh one by its prompts; only a fresh one has nothing to compact.
198    const hasConversation = now.tokens !== null || last !== null || (await $.session.turns()) > 0;
199    const isWorking = e.props.isWorking;
200    const action = [];
201
202    if (isBusy) {
203      action.push(<Text dimColor>Compacting…</Text>);
204    } else if (hasConversation) {
205      // Mid-turn, a press queues `/compact` for when the turn ends.
206      action.push(
207        <Button
208          key="compact"
209          label="Compact"
210          onPress={() => {
211            if (isWorking) $.ui.toast("Compact queued: runs when this turn ends");
212
213            return compact($);
214          }}
215        />,
216      );
217    }
218
219    return (
220      <Box
221        justifyContent="space-between"
222        alignItems="center"
223        gap={2}
224        paddingLeft={e.surface === "terminal" ? 1 : DESKTOP_INSET}
225        paddingRight={1}
226      >
227        <Box alignItems="center" gap={1}>
228          {meter}
229        </Box>
230        {action}
231      </Box>
232    );
233  });
234};
235

1// The live window as the status line reads it; null until a reply reports it.
2export type Reading = { tokens: number | null; window: number; percent: number | null };
3
4// The last compaction's sizes, kept until the next reply reports a fill.
5export type Compacted = { before: number | null; after: number | null };
6
7declare module "claude-code" {
8  interface PluginState {
9    "context-meter": {
10      reading: Reading | null;
11      compacted: Compacted | null;
12      isCompacting: boolean;
13    };
14  }
15}
16