Claude Token View
Monitor your Claude Code token usage directly in the VS Code status bar.
See your current 5-hour session usage and 7-day weekly usage at a
glance, with progress bars, color-coded levels, reset countdowns, and a
tiny pixel-art Claude mascot that idles next to the session meter.
Read-only. This extension never talks to any API and never consumes
tokens. It only reads a local cache file at
~/.claude/vscode-claude-status-cache.json. No telemetry, no network
traffic, zero runtime dependencies.
Quick start
- Open Claude Code at least once so
that the
~/.claude/ directory exists.
- Claude Code 2.1.109 or newer — open the Command Palette
(
Ctrl+Shift+P / Cmd+Shift+P) and run:
Claude Token View: Install Claude Code Status Line Hook
- Use Claude Code as usual. Two items appear in the status bar —
5h and
7d — and update each time Claude Code refreshes its statusline (every
user/assistant turn).
That's it. On Claude Code 2.1.100 or older no setup is required; the
CLI writes the cache file itself.
To stop tracking later, run Claude Token View: Uninstall Claude Code
Status Line Hook — this restores any previous statusLine command and
removes the helper script.
Reading the status bar
🟢 5h ██████░░░░ 52% 7d ████░░░░░░ 36%
- The
5h item is the current 5-hour session window.
- The
7d item is the rolling 7-day weekly window.
- Click either item to refresh immediately.
- Hover to see the exact percentage, raw bar, reset timestamp, and
remaining time.
- When a window is exhausted, the item flips to a countdown:
5h █████████░ reset in 1h 23m.
Color levels
All levels are text colors (no jarring background swaps):
| Usage |
Color |
< 50% |
green (charts.green) |
50% – 90% |
yellow (charts.yellow) |
>= 90% |
red (charts.red) |
The progress bar uses half-block characters, so 52% looks visibly
different from 50% even at the default 10-character bar length.
The mascot
A pixel-art Claude sits next to the 5h item (the 7d row stays
compact). Its expression tracks usage, and it inherits the status bar
text color — so it goes green → yellow → red along with the bar.
| Usage |
Expression |
< 50% |
happy (eyes only) |
50 – 75% |
neutral (eyes + small dash mouth) |
75 – 95% |
worried (eyes + small open mouth) |
>= 95% |
panic (eyes + wide open mouth) |
A subtle squat-and-stand idle animation runs on a 2-second cycle. Both
the mascot and its animation can be disabled — see Settings.
Notifications
Two independent toasts can fire for each window:
- A warning toast when usage crosses
sessionNotificationThreshold (default 90%) or
weeklyNotificationThreshold (default 80%).
- An error toast when the window actually hits 100%.
Each fires once per crossing and re-arms only after usage drops at least
5% below the threshold (hysteresis), so they won't spam you when you're
hovering right at the line.
How the status line hook works
Claude Code 2.1.109 stopped writing
~/.claude/vscode-claude-status-cache.json itself. Usage data is now
exposed only as a rate_limits JSON object piped to whatever statusLine
command you register in ~/.claude/settings.json.
The bundled installer wires that up for you:
- Copies
statusline-cache-writer.js to
~/.claude/claude-token-view-statusline.js.
- Registers it as
statusLine in ~/.claude/settings.json. Any
previously configured custom statusLine is preserved under
previousStatusLine so you can recover it.
- Each time Claude Code refreshes its statusline, the helper reads the
piped JSON, converts it back to the cache shape this extension
understands, and writes it atomically.
The helper is a single zero-dependency Node script — no network calls,
no external processes — it only reads stdin and writes one small JSON
file. The uninstall command restores previousStatusLine and deletes
the copied helper.
Stale data
If the cache file's updatedAt is older than
claudeTokenView.staleThresholdMinutes (default 15), the status bar
switches to a warning and the hover tooltip offers a one-click re-install
of the hook.
This typically means one of:
- The hook is not installed (or got removed from
settings.json).
- You haven't interacted with Claude Code recently. On 2.1.109+ the
statusLine fires per user/assistant turn, so idle sessions stop
refreshing the cache until you next prompt Claude.
Settings
All settings live under claudeTokenView.*.
| Setting |
Default |
Description |
claudeTokenView.enableNotifications |
true |
Show a toast when usage crosses the threshold and when the limit is reached. |
claudeTokenView.sessionNotificationThreshold |
90 |
Percent at which to notify for the 5-hour session usage. |
claudeTokenView.weeklyNotificationThreshold |
80 |
Percent at which to notify for the weekly (7-day) usage. |
claudeTokenView.refreshIntervalSeconds |
30 |
How often (seconds) to re-read the cache file as a fallback to the file watcher. |
claudeTokenView.progressBarLength |
10 |
Length of the progress bar in characters. |
claudeTokenView.showCharacter |
true |
Show the Claude mascot next to the 5-hour item. |
claudeTokenView.enableAnimation |
true |
Animate the mascot's squat-and-stand cycle. Requires showCharacter. |
claudeTokenView.animationPeriodMs |
2000 |
Full animation cycle length in milliseconds (each half = one frame). |
claudeTokenView.showSessionItem |
true |
Show the 5-hour session item in the status bar. |
claudeTokenView.showWeeklyItem |
true |
Show the weekly (7-day) item in the status bar. |
claudeTokenView.cacheFilePath |
"" |
Override the path to vscode-claude-status-cache.json. Leave empty for the default ~/.claude/. |
claudeTokenView.staleThresholdMinutes |
15 |
Minutes after which a stale-cache warning shows up with a one-click hook installer. |
Run Claude Token View: Open Settings from the Command Palette to jump
straight to the configuration UI.
Commands
| Command |
Palette title |
claudeTokenView.refresh |
Claude Token View: Refresh Now |
claudeTokenView.openSettings |
Claude Token View: Open Settings |
claudeTokenView.installStatusLine |
Claude Token View: Install Claude Code Status Line Hook |
claudeTokenView.uninstallStatusLine |
Claude Token View: Uninstall Claude Code Status Line Hook |
Clicking either status bar item also triggers a refresh.
Requirements
- VS Code
1.80 or newer
- Claude Code installed and run at
least once so that
~/.claude/ exists
Privacy
- No network requests
- No telemetry
- No tokens consumed (never calls the Anthropic API)
- Reads exactly one local file:
~/.claude/vscode-claude-status-cache.json
License
MIT — see LICENSE.
