token-weather · Claude Code mod

Preview · a replayed session in a sandbox

claude · ~/work/app · token-weather

› fix the failing auth test and add an audit log call ⏺ Read(src/auth.ts) ⎿ Read 6 lines ⏺ Update(src/auth.ts) ⎿ Added 2 lines, removed 1 line ⏺ Bash(bun test) ⎿ 3 pass, 1 fail ● Done. refresh now rejects expired claims and logs an audit event. ✻ Worked for 42s · done 4:20 PM ☁ Cloudy 49% of context 97.4k / 200k last turns ██ steady ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────── › ? for shortcuts

Draws

Band

☁ Cloudy 49% of context 97.4k / 200k last turns ██ steady

README

Token Weather

A Claude Code mod that draws a live forecast of your context window in the band above the prompt. We're sharing it as the smallest of the three mods here: one hooks module that reads real usage figures and draws one line of UI.

What this shows

 ☂  Showers  67% of context  134.4k / 200k   last turns ▁▂█  ▲ +98.3k last turn

After each turn, the band shows:

a weather icon and word for how full the window is,
the percentage used, and the tokens used out of the window,
a chart of the last 12 turns, drawn with block characters, and
how much the last turn added.

Used	Forecast
under 25%	☀ Clear
25–49%	☁ Cloudy
50–74%	☂ Showers
75–89%	☇ Storm
90% up	↯ Compact soon

The numbers are real, not estimated. After each main-loop turn, the mod calls $.session.usage() and reads context:

tokens: the input tokens the last response was answered over (uncached, cache-written and cache-read together),
window: the context window of the session's model, and
percent: tokens over window.

These are the same figures the status line shows (total_input_tokens, context_window_size, used_percentage). The call is free, because the mod doesn't ask for a breakdown, so it sends no token-count request.

Hook	What it does
`session.start`	Takes a first reading, so the band shows before the first turn.
`turn.complete`	Takes a reading after each main-loop turn. Subagent turns are skipped.
`ui.render` with `{component: "AbovePrompt"}`	Draws the band as one line.

Demo

After the first turn, 18% full:

Token Weather reading Clear at 18% of context

After reading four large files, 67% full:

Token Weather reading Showers at 67% of context

After one more file, 81% full. Claude Code's own notice reads 90%, because it counts toward the auto-compact point (see the limitations):

Token Weather reading Storm at 81% of context

How it was built

Model: built with Claude in Claude Code. The test runs and screenshots used Claude Haiku 4.5, because its 200k window shows the forecast change within a few turns. The mod itself doesn't call a model.
Prompt(s): the mod started as one of ten ideas Claude wrote for mods. This is the idea as written:

Token Weather. A live forecast of your context window. A band above the prompt draws a small chart of context use for each turn, as weather icons. It's clear when the window is mostly empty, and stormy when it's nearly full. It uses ui.render on the AbovePrompt component, with the Svg element, and it updates on turn.complete. I haven't confirmed which event or call gives the token counts, so that needs a check. Developers would share it because it looks good in a screenshot, and it answers "why did Claude forget that?" at a glance. The status line only shows text. A weekend build.

The build prompt, which picked this idea and two others by number:

implement 1,2,7. give me zips for them. test them in claude code and get me screenshots of what they look like when used.

Transcript: not shared. The build ran in an internal workspace.
Iterations:
The idea left open where the token counts come from. The build found $.session.usage(), which returns the same figures as the status line, so the mod shows real numbers rather than an estimate.
The idea drew the chart with the Svg element. The terminal can't draw Svg, so the chart is a row of block characters.
The first icons were emoji, which weren't in the test terminal's font. The mod uses single-width text symbols instead, which line up in any terminal font.
Tested in Claude Code on a test repo of five 42 KB source files: three turns, each reading more files, moved the band from ☀ 18%, to ☂ 67%, to ☇ 81%.

Run it

Requirements:

Claude Code 2.1.287 or later, where mods load by default. The mod was built and tested on 2.1.280, and claude plugin validate passes on 2.1.285.
A terminal. AbovePrompt is drawn on the terminal surface only.

No environment variables or configuration.

Steps:

Clone this repository and go to this folder's parent:

   git clone https://github.com/anthropics/claude-code-playground.git
   cd claude-code-playground/claude-code/mods

Check the plugin:

   claude plugin validate ./token-weather

Try it for one session:

   claude --plugin-dir ./token-weather

Or install it, with the other mods here, from the local marketplace in this folder (see the mods README):

   claude plugin marketplace add ./
   claude plugin install token-weather@claude-code-playground-mods --scope user

Work as normal. The band updates after each turn.

Notes / limitations

The percentage is of the full window. Claude Code's own "context used" notice counts against the auto-compact point, which is lower, so the two can differ. In testing, the band read 81% when the notice read 90%.
The band updates once per turn, not during a turn.
The chart's bars are relative to the fullest turn shown, so growth shows even at low fill. The percentage is the absolute figure.
The history resets when the session starts, or when the plugin reloads.
On a 1M-token window, ordinary work stays at ☀ for a long time. That's accurate.
One band per session. Another plugin that draws AbovePrompt competes for the same band.
Before the first response, the band reads 0%, because no response has reported usage yet.

Dependencies

Name	Version	License (SPDX)	Source
None

Third-party notices

None.

Shared as-is as part of claude-code-playground. Not an official Anthropic product; no support or maintenance is implied. See the root README and LICENSE.

Source 1 files

hooks/token-weather.mjs 123 lines

1// Copyright 2026 Anthropic PBC
2// SPDX-License-Identifier: Apache-2.0
3//
4// Token Weather: a live forecast of the context window, above the prompt.
5//
6// turn.complete: after each main-loop turn, read the context window's fill
7// from $.session.usage() (the same figures the status line shows) and keep
8// the last HISTORY readings.
9// session.start: take a first reading, so the band shows before any turn.
10// ui.render (AbovePrompt): one line: icon, forecast word, percent, tokens
11// used of the window, and a block-character chart of the recent turns.
12//
13// The host reads on(...) and $.noun.method(...) from source, so they are
14// spelled literally, and helpers that take $ are top-level functions.
15
16const HISTORY = 12;
17const BARS = "▁▂▃▄▅▆▇█";
18
19// Forecast bands, by percent of the window used.
20const FORECAST = [
21// Single-width text symbols, not emoji: they line up in every terminal font.
22  { upTo: 25, icon: "☀", word: "Clear", color: "yellow" },
23  { upTo: 50, icon: "☁", word: "Cloudy", color: "cyan" },
24  { upTo: 75, icon: "☂", word: "Showers", color: "blue" },
25  { upTo: 90, icon: "☇", word: "Storm", color: "magenta" },
26  { upTo: Infinity, icon: "↯", word: "Compact soon", color: "red" },
27];
28
29// Readings: { tokens, window, percent }, oldest first.
30let readings = [];
31
32export function register(on) {
33  on("session.start", async ($, e, next) => {
34    const result = await next(e);
35    readings = [];
36    await takeReading($);
37    return result;
38  });
39
40  on("turn.complete", async ($, e, next) => {
41    const result = await next(e);
42    if (e.agentId) {
43      return result;
44    }
45    await takeReading($);
46    return result;
47  });
48
49  on("ui.render", { component: "AbovePrompt" }, ($, e, next) => {
50    if (e.hasSurvey || readings.length === 0) {
51      return next(e);
52    }
53    const { Box, Text } = $.ui.resolve(e);
54    return band(Box, Text, e.bodyColumns ?? 80);
55  });
56}
57
58async function takeReading($) {
59  try {
60    const { context } = await $.session.usage();
61    if (!context || !context.window) {
62      return;
63    }
64    const tokens = context.tokens ?? 0;
65    const percent = Math.round(context.percent ?? (tokens / context.window) * 100);
66    // The session.start reading is 0 before any response; drop it once real readings arrive.
67    readings = readings.filter((r) => r.tokens > 0);
68    readings.push({ tokens, window: context.window, percent });
69    if (readings.length > HISTORY) {
70      readings = readings.slice(-HISTORY);
71    }
72    $.ui.invalidate("ui.render");
73  } catch {
74    // No reading this turn; the band keeps the last one.
75  }
76}
77
78function band(Box, Text, columns) {
79  const now = readings[readings.length - 1];
80  const f = forecastFor(now.percent);
81  const trend = trendWord();
82  const parts = [
83    Text({ color: f.color, bold: true, children: `${f.icon}  ${f.word}` }),
84    Text({ children: `  ${now.percent}% of context` }),
85    Text({ dimColor: true, children: `  ${short(now.tokens)} / ${short(now.window)}` }),
86  ];
87  if (columns >= 60) {
88    parts.push(Text({ dimColor: true, children: "   last turns " }));
89    parts.push(Text({ color: f.color, children: chart() }));
90    if (trend) {
91      parts.push(Text({ dimColor: true, children: `  ${trend}` }));
92    }
93  }
94  return Box({ flexDirection: "row", paddingX: 1, children: parts });
95}
96
97function forecastFor(percent) {
98  return FORECAST.find((band) => percent < band.upTo) ?? FORECAST[FORECAST.length - 1];
99}
100
101// Bars scale to the busiest reading shown, so growth shows at any fill level.
102function chart() {
103  const top = Math.max(...readings.map((r) => r.tokens), 1);
104  const bars = readings.map((r) => BARS[Math.min(BARS.length - 1, Math.floor((r.tokens / top) * (BARS.length - 1)))]);
105  return bars.join("");
106}
107
108function trendWord() {
109  if (readings.length < 2) {
110    return "";
111  }
112  const delta = readings[readings.length - 1].tokens - readings[readings.length - 2].tokens;
113  if (delta > 0) return `▲ +${short(delta)} last turn`;
114  if (delta < 0) return `▼ ${short(-delta)} last turn`;
115  return "steady";
116}
117
118function short(n) {
119  if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(n % 1_000_000 === 0 ? 0 : 1)}M`;
120  if (n >= 1_000) return `${(n / 1_000).toFixed(n % 1_000 === 0 ? 0 : 1)}k`;
121  return String(n);
122}
123