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

1. Open Claude Code at least once so that the ~/.claude/ directory exists.
2. 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

3. 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):

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.

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 90%).
• An error toast when the window actually hits 100% (max), including the time remaining until that window resets.

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.

Both close themselves after claudeTokenView.notificationAutoDismissSeconds (default 10) — the notification's progress bar is the countdown, and its cancel button closes it immediately. Set the value to 0 if you'd rather have a notification that stays until you dismiss it and carries an "Open Settings" button.

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:

1. Copies statusline-cache-writer.js to ~/.claude/claude-token-view-statusline.js.
2. Registers it as statusLine in ~/.claude/settings.json. Any previously configured custom statusLine is preserved under previousStatusLine so you can recover it.
3. 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

The statusLine hook only ticks while Claude Code is running, so the cache naturally stops refreshing whenever you're not actively prompting Claude. That's normal and not an error — an idle session consumes no tokens, so the last-known usage stays accurate and the reset countdown keeps ticking. The extension keeps showing those numbers; the tooltip notes how long ago the cache was last updated.

The stale warning (with a one-click hook installer) only appears when the cache is older than claudeTokenView.staleThresholdMinutes (default 15) and the statusLine hook is not installed in ~/.claude/settings.json — i.e. the genuine setup problem where the cache would never refresh. Once the hook is installed, idle sessions no longer trigger the warning.

Settings

All settings live under claudeTokenView.*.

Run Claude Token View: Open Settings from the Command Palette to jump straight to the configuration UI.

Commands

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.