token-weather

token-weather draws a one-line forecast of your context window in the band above the Claude Code prompt. After each turn it shows a weather icon, the share of the window in use, tokens used out of the window, a bar chart of the last 12 turns and how much the last turn added.

The forecast runs from Clear (under 25%) through Cloudy, Showers and Storm to Compact soon at 90% and up. The mod comes from claude-code-playground, where Anthropic’s Claude Code DevRel team shares examples as-is, with no support promised. At version 0.1.0 and about 120 lines in one hooks module, it is the smallest of the three mods there, and the easiest to read before you write your own with the mods documentation.

Install

Needs Claude Code 2.1.287 or later.

git clone https://github.com/anthropics/claude-code-playground.git
cd claude-code-playground/claude-code/mods
claude plugin marketplace add ./
claude plugin install token-weather@claude-code-playground-mods --scope user

The marketplace file sits in claude-code/mods, not at the root of the repo, so the mod’s README adds it from a local clone. The same marketplace also offers blast-radius and replay-theater. To try token-weather for one session without installing it, run claude --plugin-dir ./token-weather from that folder.

Then work as normal. The band appears at session start and updates after every turn.

How it works

After each main-loop turn, the mod calls $.session.usage() and reads the context figures: the input tokens the last response was answered over (cached or not), the model’s window, and the percentage between them. They are the numbers the status line receives, not an estimate. It asks for no breakdown, so the call sends no token-count request and costs nothing.

Subagent turns are skipped. The readings live in memory only: nothing is written to disk and there are no network calls.

Limitations

• The percentage is of the full window. Claude Code’s own notice counts toward the auto-compact point, which is lower, so it reads higher: 90% in the author’s test while the band said 81%.

• It updates once per turn, not during one. Before the first response it reads 0%.
• The chart’s bars are relative to the fullest turn shown, so growth is visible even at low fill. The percentage is the absolute figure.
• The history resets when a session starts or the plugin reloads.
• On a 1M-token window, ordinary work stays Clear for a long time.
• Only one mod can draw in the band above the prompt. Another one that draws there competes for it.
• The author notes that the band above the prompt is drawn on the terminal only.