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.

Claude Code 2.1.109+: the CLI no longer writes that cache file on its own — usage data is now exposed only as rate_limits JSON piped to a user-registered statusLine command. Run Claude Token View: Install Claude Code Status Line Hook once (see Setup below) and the bundled helper will rebuild the cache file each time Claude Code refreshes its statusline.

Features

• Two status bar items: 5-hour session (5h) and 7-day weekly (7d) usage, each with its own progress bar and percentage.

• Half-block progress bar so 52% visibly differs from 50% even at the default 10-character bar length.

• Foreground-only color levels — all three levels are text colors, so the bar never jarringly swaps to a coloured background:

  Usage	Color
  < 50%	green text (charts.green)
  50% – 90%	yellow text (charts.yellow)
  >= 90%	red text (charts.red)

• Animated pixel-art Claude mascot next to the 5-hour item (kept off the weekly item so the row stays compact). Shipped as a custom WOFF font contributed by the extension, so the mascot inherits the status bar text color (green / yellow / red). Four expressions:

  Usage	Mascot
  < 50%	happy (eyes only)
  50 – 75%	neutral (eyes + small dash mouth)
  75 – 95%	worried (eyes + small open mouth)
  >= 95%	panic (eyes + wide open mouth)

• Squat-and-stand idle animation: the mascot's body bobs down a few pixels (legs compressed, feet planted) on a 2-second cycle. Configurable period, can be turned off entirely.

• Reset countdown: once a window is exhausted, the item switches from e.g. 5h █████░░░░░ 52% to 5h █████████░ reset in 1h 23m.

• Two-stage notifications:

  • A warning toast fires when session usage crosses 90% (default) or weekly usage crosses 80% (default).
  • A separate error toast fires when a window actually hits 100%. Both can fire for the same climb — one at the threshold, another when the limit is reached.
  • Each fires once per crossing; re-arms after usage drops at least 5% below the threshold (hysteresis).

• Tooltip on hover shows the exact percentage, raw bar, reset timestamp, and remaining time.

• Live updates via fs.watch on the cache file, plus a configurable polling fallback (default 30 s).

Install

From the Marketplace

Search for "Claude Token View" in the VS Code Extensions view, or:

code --install-extension Roki.claude-token-view

From a .vsix

Download the latest claude-token-view-<version>.vsix from the Releases page and install it:

code --install-extension claude-token-view-0.1.0.vsix

Or in VS Code: Extensions view → … menu → Install from VSIX….

Setup

On Claude Code 2.1.109+ run the bundled installer once:

Command Palette → Claude Token View: Install Claude Code Status Line Hook

This performs three things:

1. Copies scripts/statusline-cache-writer.js to ~/.claude/claude-token-view-statusline.js.
2. Adds a statusLine entry to ~/.claude/settings.json pointing at that copy (preserving any previous custom statusLine as previousStatusLine).
3. Starts renderng usage as soon as Claude Code next updates its statusline (every user/assistant turn, or on the configured refreshInterval).

The helper script is dependency-free, makes no network calls, and only reads stdin + writes one small JSON file. See How it works for the full data flow.

To revert: Claude Token View: Uninstall Claude Code Status Line Hook. This restores any pre-existing statusLine and deletes the copied helper.

On Claude Code ≤ 2.1.100 no setup is required — the CLI still writes the cache file directly.

How it works

The extension reads usage from:

~/.claude/vscode-claude-status-cache.json

{
  "version": 2,
  "updatedAt": "2026-04-14T12:06:33.676Z",
  "usageData": {
    "utilization5h": 0.52,
    "utilization7d": 0.36,
    "reset5hAt": 1776178800,
    "reset7dAt": 1776434400,
    "limitStatus": "allowed"
  }
}

Who writes the cache?

On 2.1.109 the CLI moved usage tracking to response-header parsing (anthropic-ratelimit-unified-5h-utilization, ...-7d-utilization, etc.) and now only exposes it to user-configured statusLine commands as rate_limits.five_hour.used_percentage / seven_day.used_percentage in the JSON piped on stdin.

The helper reads that stdin, converts it back to the legacy cache shape, and writes the file atomically. The extension watches the file exactly as before — so the same render code path works on both versions.

When the cache's updatedAt is older than claudeTokenView.staleThresholdMinutes (default 15), the status bar switches to a warning and the tooltip offers one-click install of the hook.

Settings

All settings live under claudeTokenView.*.

Commands

Clicking either status bar item also triggers a refresh.

Requirements

• VS Code >= 1.80
• Claude Code installed and run at least once, so the cache file exists.

Privacy

• No network requests
• No telemetry
• No tokens consumed (does not call the Anthropic API)
• Reads exactly one local file: ~/.claude/vscode-claude-status-cache.json

Known limitations

• On Claude Code 2.1.109+, usage updates only happen while a Claude Code session is running (the helper is driven by its statusLine, which is evaluated per user/assistant turn). Idle users will see a stale warning until the next Claude Code interaction.
• When limitStatus is anything other than "allowed", the item color is forced to red regardless of the raw percent. The helper cannot populate this field on 2.1.109+ (it is not part of the statusLine JSON), so the limit-status colour override is effectively disabled on newer CLIs — exhaustion still shows as red via the 100 % raw-percent threshold.

Contributing & development

git clone https://github.com/IwataHiroki0827/ClaudeTokenView.git
cd ClaudeTokenView
npm install
npm run build:icons      # SVG → WOFF
npm run build:icon-png   # SVG → Marketplace icon
npm run compile          # TypeScript

Then press F5 in VS Code to launch an Extension Development Host.

To redesign the mascot: edit the SVGs under icons/ (32×32 viewBox), then run npm run preview:icons to render images/preview.png and npm run build:icons to regenerate the WOFF.

See PUBLISHING.md for the Marketplace publishing flow.

License

MIT — see LICENSE.