token-weather

1// Token Weather: a live forecast of the context window, above the prompt.
2
3const HISTORY = 12;
4const BARS = "▁▂▃▄▅▆▇█";
5const FORECAST = [
6  { upTo: 25, icon: "☀", word: "Clear", color: "yellow" },
7  { upTo: 50, icon: "☁", word: "Cloudy", color: "cyan" },
8  { upTo: 75, icon: "☂", word: "Showers", color: "blue" },
9  { upTo: 90, icon: "☇", word: "Storm", color: "magenta" },
10  { upTo: Infinity, icon: "↯", word: "Compact soon", color: "red" },
11];
12
13// Held by the host, so the history survives a hot reload of this file.
14const readings = { plugin: "token-weather", key: "readings" };
15
16export function register(on) {
17  on("session.start", async ($, e, next) => {
18    const result = await next(e);
19    await takeReading($);
20    return result;
21  });
22
23  on("turn.complete", async ($, e, next) => {
24    const result = await next(e);
25    if (!e.agentId) {
26      await takeReading($); // main-loop turns only, not subagents
27    }
28    return result;
29  });
30
31  on("ui.render", { component: "AbovePrompt" }, async ($, e, next) => {
32    const { value: history = [] } = await $.state.get(readings);
33    if (e.props.hasSurvey || history.length === 0) {
34      return next(e);
35    }
36    const { Box, Text } = $.ui.resolve(e);
37    return band(Box, Text, history, e.props.bodyColumns);
38  });
39}
40
41async function takeReading($) {
42  const { context } = await $.session.usage();
43  if (!context?.window) return;
44  const tokens = context.tokens ?? 0;
45  const percent = context.percent ?? Math.round((tokens / context.window) * 100);
46  const { value: history = [] } = await $.state.get(readings);
47  await $.state.set(readings, [...history, { tokens, window: context.window, percent }].slice(-HISTORY));
48}
49
50function band(Box, Text, history, columns) {
51  const now = history[history.length - 1];
52  const f = FORECAST.find((b) => now.percent < b.upTo);
53  const parts = [
54    Text({ color: f.color, bold: true, children: `${f.icon}  ${f.word}` }),
55    Text({ children: `  ${now.percent}% of context` }),
56    Text({ dimColor: true, children: `  ${short(now.tokens)} / ${short(now.window)}` }),
57  ];
58  if (columns >= 60) {
59    parts.push(Text({ dimColor: true, children: "   last turns " }));
60    parts.push(Text({ color: f.color, children: sparkline(history) }));
61    if (history.length > 1) {
62      parts.push(Text({ dimColor: true, children: trend(history) }));
63    }
64  }
65  return Box({ flexDirection: "row", paddingX: 1, children: parts });
66}
67
68function sparkline(history) {
69  const top = Math.max(...history.map((r) => r.tokens), 1);
70  return history.map((r) => BARS[Math.floor((r.tokens / top) * (BARS.length - 1))]).join("");
71}
72
73function trend(history) {
74  const delta = history[history.length - 1].tokens - history[history.length - 2].tokens;
75  if (delta === 0) return "  steady";
76  return delta > 0 ? `  ▲ +${short(delta)} last turn` : `  ▼ ${short(-delta)} last turn`;
77}
78
79function short(n) {
80  if (n >= 1_000_000) return `${+(n / 1_000_000).toFixed(1)}M`;
81  if (n >= 1_000) return `${+(n / 1_000).toFixed(1)}k`;
82  return String(n);
83}
84

1export type TokenWeatherReading = { tokens: number; window: number; percent: number };
2
3declare module "claude-code" {
4  interface PluginState {
5    "token-weather": { readings: TokenWeatherReading[] };
6  }
7}
8