Desktop · GNOME Shell
Token Usage Widget
A GNOME Shell top-bar extension that surfaces meaningful Claude Code token usage at a glance — a colour-coded 5-hour rolling window, a daily breakdown, and an hourly burn sparkline — built because the raw numbers are misleading.
- GNOME Shell (GJS)
- JavaScript (ESM)
- Python
- Gio.Subprocess
- GLib
// live in the top bar — refreshes every 60s
Overview
Anthropic doesn't expose Max-plan limits as a token count, and the raw daily "total" is dominated by cache-reads — about 97% discounted — so it badly overstates real consumption. This extension parses the local Claude Code logs, isolates the tokens that actually count, and shows the meaningful figure right in the GNOME top bar, refreshing every minute.
What it shows
⏱️ 5-hour window
The headline figure tracks a rolling 5-hour window — matching the plan's throttling window — colour-coded from default to amber to red.
📊 Daily breakdown
The dropdown breaks out Last 5h, Today and Last 7 days, plus a full breakdown of today's usage.
📈 Burn sparkline
An hourly sparkline shows how today's usage built up over time, so spikes are obvious at a glance.
🎯 Real tokens only
Counts input + output + cache-creation and excludes the heavily-discounted cache-reads that inflate the raw total.
How it works
- Parse: a Python script reads the local Claude Code JSONL logs, filters by local calendar day, and de-duplicates responses before emitting JSON.
- Display: a GNOME 45+ ESM extension renders the indicator and dropdown, refreshing every 60 seconds.
- Stay smooth: the parser is spawned asynchronously via
Gio.Subprocessso it never blocks the compositor. - Tune it: the amber/red thresholds are constants at the top of
extension.js, easy to recalibrate against observed limits.