Claude Code Usage Meter

Live Claude Code usage in the VS Code status bar — session and weekly rate-limit meter, token and cost tracking, per-model and per-session breakdown.

A usage monitor for Claude Code that shows how much of your Claude session limit and weekly limit you have burned, how many tokens and dollars each model and session has cost, and how fast you are burning through the current window. Works with Claude Pro, Max and API accounts.

Reads the transcripts Claude Code already writes to ~/.claude/projects and turns them into a meter you can glance at while you work. Nothing leaves your machine.

What it shows

Status bar — a chunk meter for the current session limit, percent used, and time until it resets:

██████▎░░░  62% · 1h47m

The item turns amber at the warning threshold and red at the danger threshold. Click it to open the dashboard, or set it to cycle between block / week / today / session.

Width is fixed for every value — percentages reserve three digits and durations are always NhNNm — so nothing in the status bar cluster shifts as the numbers tick.

Eight meter styles are available. The default, halfblocks (██████▎░░░), resolves to ~1.25% per cell and creeps rather than stepping. Block elements share a single advance width in every monospace font, so the meter never changes size as it fills.

circles (●●●●●●◔○○○) resolves to 2.5% per cell — four times finer than the block meters — and the partial cell is the easiest to spot mid-glance; but mixes Unicode blocks — ○, ● and ◔ come from different ranges and many editor fonts draw them at visibly different sizes. Try it, and fall back to circleHalves or ticks (▰▰▰▰▰▰▱▱▱▱) if it looks uneven. halfblocks resolves to ~1.25% and creeps rather than steps, and ascii renders anywhere.

Dashboard — a side panel with:

• session and weekly limit gauges, with a caret marking where the current burn rate lands by reset
• the session gauge as a bar or, with claudeUsage.dashboard.gaugeStyle, a ring where the projection tick reads as a position in the window
• per-model weekly figures when your account is connected
• today, active session, burn rate (tokens/min) and total tiles
• per-model table with tokens, cost and message counts
• live session list, active sessions marked
• 30-day history bars

Install

From the VS Code Marketplace: search Claude Code Usage Meter.

From a .vsix:

code --install-extension claude-code-meter-0.4.0.vsix

How the numbers are built

Every assistant message Claude Code writes carries a usage block. This extension sums them, with three corrections that matter:

• Deduplication. One logical assistant message is written as several JSONL lines (one per content block), and resumed sessions copy earlier lines verbatim. Lines are keyed on (message.id, requestId), so nothing is counted twice — without this, totals roughly double.
• Cache tiers are priced apart. cache_creation splits into 5-minute and 1-hour TTLs, billed at 1.25× and 2× the input rate. They are costed separately, not lumped together.
• Subagents count. Sidechain messages are real usage and are included by default (claudeUsage.includeSubagents turns them off).

Only bytes appended since the last pass are parsed, so a refresh costs a few milliseconds even with tens of thousands of transcripts on disk. A filesystem watcher triggers a refresh the moment Claude Code writes, with polling as a fallback.

Where the percentages come from

Limit percentages cannot be derived from transcript tokens. Claude computes them server-side, and they are weighted very differently from raw usage: a session window holding 68M transcript tokens reports single-digit utilization, because cache reads — which dominate every total — barely count toward the limit. Any extension that sums JSONL tokens and calls the result a percentage is guessing, and will be wrong by an order of magnitude.

So percentages come from your account, the same source /usage reads — using the Claude Code sign-in already on this machine. There is nothing to set up: if you are signed in to Claude Code, the session and weekly gauges match /usage exactly, including the per-model weekly figures. macOS asks once for keychain access the first time VS Code reads it.

If no sign-in can be found (or the store is unreadable), Claude Usage: Paste Account Token takes a token from claude setup-token and keeps it in VS Code's encrypted secret storage.

Estimates without an account

The meter works without connecting anything. With no account, percentages are estimated against a plan ceiling and shown with a tilde — ~14% — so an estimate never reads as a measurement. claudeUsage.plan picks the ceiling; auto infers your plan from the largest block this machine has reached.

Be clear about what these are worth: Anthropic publishes limits as percentages, never as token counts, so any token-based ceiling is a model. The presets here are back-calculated from a measured account — 159M counted tokens reported as 60% of a session, 1.82B as 38% of a week — rather than guessed. They are still only as good as that one observation: the weighting Anthropic applies is not public, and cache reads appear to count for far less toward a limit than they contribute to these totals, so an account whose traffic has a different shape will read proportionally wrong. Claude Usage: Calibrate Estimate from /usage fixes that in ten seconds: enter the percentage Claude Code reports and the ceiling is derived from the tokens counted here. Connect your account and the tilde disappears along with the guesswork.

Without a sign-in the extension still works — tokens, cost, burn rate, per-model and per-session breakdowns, all local — but it shows no percentage, rather than a fabricated one. If you want a meter anyway, set claudeUsage.blockTokenLimit and claudeUsage.weeklyTokenLimit to ceilings of your own choosing.

Costs use the published per-million-token API rates, including cache write and read multipliers. On a subscription the dollar figure is notional — what the same traffic would cost on the API. Turn it off with claudeUsage.cost.enabled, or override rates per model with claudeUsage.cost.pricing.

Settings

Full list with descriptions: Settings → Extensions → Claude Code Usage Meter.

Commands

Privacy

The extension reads local transcript files — only their usage counters, model ids, timestamps, session ids and working-directory names, never message content. It has no telemetry and sends nothing anywhere.

For limit percentages it makes exactly one kind of network request: a periodic GET https://api.anthropic.com/api/oauth/usage carrying your existing Claude Code credential, which returns your own limit percentages. The credential is read from the local store Claude Code already uses — it is never copied, written elsewhere, or sent anywhere but that endpoint. Set claudeUsage.source to transcripts to disable the lookup entirely.

Development

npm install
npm run compile      # bundle to out/
npm run watch        # rebuild on change
npm run typecheck    # tsc --noEmit
npm run package      # build a .vsix

Press F5 in VS Code to launch an Extension Development Host.

Licence

MIT