Claude Usage

Your Claude plan limits and token spend, live in the VS Code status bar.

Two gauges, always visible: the 5-hour session window and the 7-day rolling window. Hover for the full breakdown.

What it shows

Where the numbers come from

Two separate sources, and the distinction matters.

Rate limits come from Anthropic's usage endpoint, queried with the OAuth token Claude Code keeps in ~/.claude/.credentials.json — the same source the /usage command reads. The file is read locally, the token only ever travels to api.anthropic.com, and it is re-read on every cycle so session renewals are picked up automatically.

That endpoint is not publicly documented and may change without notice. When it fails, the last valid reading stays on screen with its timestamp, and the panel falls back to local statistics if there is none. Set claudeUsage.enableRateLimits to false to turn the whole section off.

Its quota is shared with Claude Code, which polls the same endpoint for its own display, so an active session can saturate it alone. The endpoint then answers 429 with an unusable Retry-After: 0. The extension applies exponential backoff — the interval doubles on each consecutive failure, capped at 30 minutes, and resets on the first success — and skips polling entirely while the window is unfocused. Ctrl+Alt+R overrides the backoff.

Token statistics come from the local transcripts under ~/.claude/projects/. No network, no authentication. Subagent transcripts are counted, internal <synthetic> messages are discarded, and duplicates from session resumes are deduplicated.

About the cost figure

The cost is an API equivalent: what the same consumption would cost pay-as-you-go, computed by applying the public rate card to the observed tokens, cache included (read 0.10×, write 5m 1.25×, write 1h 2×).

On a Pro or Max plan, that is not what you are billed. The subscription is measured in window percentages, not dollars — which is what the Rate Limits section shows. The figure remains useful as a relative measure: which project is expensive, which day was heavy.

Settings

Shortcuts

• Ctrl+Alt+R (Cmd+Alt+R on macOS) — refresh immediately
• Clicking the badge also refreshes

Refresh behaviour

Local statistics update as soon as a transcript changes, through a file watcher that collapses write bursts into a single pass. A safety rescan runs every minute in case an event is missed. Rate limits are polled every 5 minutes by default, and only while the window has focus.

A full pass over ~130 MB of transcripts takes about 500 ms at startup; later passes are incremental and cost a few milliseconds, because each file keeps a cursor on the bytes already read.

Building from source

npm install
npm run compile
npm test
npx vsce package
code --install-extension claude-usage-0.1.0.vsix --force

If you use a VS Code profile, that last command is not enough: it installs into the default profile and the extension will never appear in the active window. Name the profile explicitly:

code --profile "<profile-name>" --install-extension claude-usage-0.1.0.vsix --force

The profile name is in ~/.config/Code/User/globalStorage/storage.json, under userDataProfiles. Without the command line: Extensions view → ... menu → Install from VSIX…, which always targets the active profile.

Either way, reload the window afterwards (Developer: Reload Window).

Press F5 from the repository for a development host with hot reload.

Privacy

Nothing is collected, stored remotely, or sent anywhere. The OAuth token is read from disk and used for a single request to api.anthropic.com. Transcripts are parsed in memory and never leave the machine.

License

MIT