Claude Code Usage & Cost Tracker

A VS Code / Cursor extension that surfaces your Claude Code plan-limit usage, context window, token counts, estimated cost, and usage trends from your local logs — in the status bar and a dashboard.

_{At a glance in the status bar — plan limits, context, cost, and tokens. The pace meter 5h 42% → 53% reads “at your current rate you're on track to finish the 5‑hour window at 53%.”}

_{Hover any status-bar item for the full breakdown — here near the end of the 5‑hour window at 89%: each plan limit with its reset time and the · on pace reading, your burn rate split into new work versus cached context re-reads, and context-window fill.}

Features

• Status bar — plan-limit utilization (5-hour + weekly, optional weekly-Opus), each led by a Claude sunburst that turns green / yellow / red at your own warning thresholds (predictiveAlerts.warnThresholds, 75% / 90% by default), plus the current session's context-window fill, today's estimated cost, and token count. Each segment toggles independently. Click any of them to open the dashboard.
• Plan limits — real 5h / weekly usage with reset times and per-model scoped windows, shown as bars in the dashboard. Fetched live from Anthropic's usage endpoint (the same call Claude Code makes) so the numbers stay current even mid-session, with Claude Code's on-disk cache as a fallback. Multiple open editor windows share a single fetch, so opening more windows won't rate-limit you onto a stale reading.
• Predictive alerts — forecasts when you'll hit a limit and warns you before you do. The 5-hour limit gets a live pace meter: 5h 42% → 53% means at your current rate you're on track to finish the 5-hour window at 53% (it climbs toward 100% as you push harder, so you can see at a glance whether you're cruising or about to run out). It appears once the window is half over and you're actively burning, and reads · on pace near 100% rather than committing to a knife-edge number — so it doesn't cry wolf. The weekly limit shows a time-to-limit ETA only when you're genuinely on track to breach it. Notifications fire at configurable thresholds (75% / 90%) and when your pace is clearly set to breach a window before it resets, and the tooltip shows your live burn rate, split into new work versus cached context re-reads (a long session re-reads its whole context every turn, which otherwise dominates the figure and makes it meaningless). An optional, off-by-default model-cost advisor suggests a cheaper model when you're burning an expensive one on routine turns. On by default and 100% local — configure under predictiveAlerts.*.
• Extra usage (pay-as-you-go) — optional, off by default: when your account has pay-as-you-go enabled, your spend beyond plan limits is shown in the status bar (extra $3.50 / $50.00), the tooltip, and the dashboard. Turn on with showExtraUsage.
• Context window — the latest request's prompt size as a percent of the model's window (like /context), with 1M-tier detection.
• Advisor — a panel in the dashboard with ranked, money-quantified tips to cut waste this month: routing routine turns to a cheaper model (with the estimated saving), long sessions that re-processed context uncached, sessions running near the context limit, and a month-end spend forecast. Subscription-aware: on a Pro/Max plan (where you pay a flat fee, not per token) it labels the dollar figures as estimated API-equivalent usage — a gauge, not a bill — and frames the advice around your 5-hour / weekly session limits. Computed entirely from your local usage data — no network call, no API key, and your prompts never leave your machine. On by default; turn it off with advisor.enabled. An optional Explain with AI button turns those signals into written, prioritized coaching — it calls Anthropic with your own API key — a pay-as-you-go key from the Anthropic Console, separate from your Claude Code subscription — stored in VS Code Secret Storage (set via the Set Anthropic API Key command, which links you straight to the console), sends only the usage summary by default, and never uses your Claude Code login. Prompt text is included only if you opt in (advisor.ai.includePrompts) and confirm.
• Dashboard — Today / This Month / All Time cards with a full input / output / cache-write / cache-read token breakdown, cache-hit rate, and a cost-composition bar. Below them, sortable breakdowns: by model, by project (grouped by git repo, folder, or path), by git branch, and by session (titles, peak context, active-time duration) — each footed with a totals row (messages, tokens, cost).
• Trend — a bar chart of usage over time: daily across the current month or monthly across all time, switchable between cost and tokens, with the current day highlighted and a running total / peak summary. Empty days and months are filled in, so gaps in usage stay visible.
• Live updates — file watchers over your logs and the limits cache refresh the moment Claude Code writes, with a timer as a fallback.
• Cost estimates — from a per-model price table, with prefix matching for dated and suffixed model ids.

How it works

Claude Code writes a JSONL transcript per session under ~/.claude/projects. The extension walks those logs and parses each line into a per-message usage record — capturing model, working directory, git branch, and session id. A message is written once per streamed content block, and only the final line of the group carries the settled token counts (the earlier ones hold a placeholder), so duplicates collapse to that last entry rather than the first. Records are aggregated by day, month, and all-time, and grouped by model, project, branch, and session, then priced with a per-model rate table. The daily and monthly aggregates feed the trend chart; the rest feed the cards and breakdown tables.

Plan limits come from a second source. By default the extension fetches them live from Anthropic's usage endpoint (GET /api/oauth/usage on api.anthropic.com) — the same call Claude Code makes — authenticated with Claude Code's OAuth token (from ~/.claude/.credentials.json, or the login Keychain on macOS, where Claude Code keeps it instead). This keeps the 5-hour and weekly figures current even during a long session, when Claude Code's own on-disk cache (~/.claude/usage-cache.json) can sit hours stale. If the live request fails for any reason, the extension falls back to that cache file; a window whose reset time has already passed is treated as rolled over (a fresh 0%) with an "Updated X ago" note so a stale reading is never styled like a live one. The utilization figures are already 0–100, so they're shown as-is; the green / yellow / red tint follows your own warnThresholds (an explicit warning from the server can raise it, never lower it). The context-window figure is the most recent request's prompt size (input + cache) over the model's window — 200K, or 1M when the prompt or model marks the long-context tier.

Privacy. The live fetch reads your OAuth token from ~/.claude/.credentials.json (honoring CLAUDE_CONFIG_DIR), or from the login Keychain on macOS, read-only — it is never written back — and talks only to Anthropic's own hosts (api.anthropic.com for usage, and platform.claude.com only if the token needs refreshing, which is held in memory). Set useLiveApi to false to read only the local cache file and make no network requests.

The Advisor panel is computed entirely on-device. Its optional Explain with AI button is the one feature that sends data off-device, and only when you click it: it POSTs your usage summary to api.anthropic.com/v1/messages authenticated with your own Anthropic API key — created at console.anthropic.com/settings/keys (a pay-as-you-go API key, separate from and billed independently of your Claude Code subscription) and kept in VS Code Secret Storage, never the Claude Code OAuth token. By default only metadata is sent — token counts, costs, cache figures, model names, and the locally-computed tips, never any prompt or response text. Prompt text is included only if you both turn on advisor.ai.includePrompts and confirm the modal each time, in which case a small, truncated sample of recent prompts is added so it can coach on prompt quality. The key is read locally and never leaves your machine; it is never bundled with the extension or shared with anyone else.

_{“Explain with AI” turns the local signals into prioritized, written coaching — called with your own API key, framed around your plan limits when you're on a subscription.}

If your account has pay-as-you-go extra usage enabled, that same usage response carries your spend beyond plan limits. With showExtraUsage on (it is off by default), the extension shows it as extra <spent> / <cap> in the status bar and an Extra usage section in the dashboard. Amounts come straight from Anthropic (minor units + currency); nothing is shown when your account has extra usage disabled.

Predictive alerts turn those limit figures into a forecast, computed from your average consumption over the current window so far (resets_at minus the window's length gives the start), so each window is judged on its own timescale — the 5-hour window over hours, the 7-day window over days.

The 5-hour window shows a live pace meter: the projected end-of-window utilization at your current rate (5h 23% → 45%), climbing toward 100% as you burn faster. Early in the window it damps that projection toward your current utilization, because the raw extrapolation divides by the elapsed time and a tenth of the way in one percentage-point tick becomes ten (5h 15% would read a raw → 150%); the meter firms up to the plain projection by the time the window is half over. It stays visible while you're idle — there it simply eases downward on its own — but the breach popup still needs recent activity, so a heavy start followed by an hour of nothing won't keep warning you. And within ten points of 100% it reads · on pace rather than a number, because there the projection is a coin flip that flips back on the next refresh. The weekly window stays quiet and shows a time-to-limit ETA only once you're on a trustworthy track to breach it before reset (its figure moves over days, so a constant readout would be noise).

Threshold and pace-based warnings fire once per window (re-arming when it resets), only while you're actually burning, and — for the pace warning — only once you're clear of that same on-pace band, so a popup never contradicts the meter. It all runs on the figures already on screen and makes no extra network calls.

_{A heads-up before you run out — fired only when you're projected to run past a limit before it resets, not merely on pace to use the window fully.}

Getting started

1. Install from the VS Code Marketplace or Open VSX, or download a .vsix from the Releases page and run code --install-extension <file>.vsix (or, in Cursor, cursor --install-extension <file>.vsix).
2. Use Claude Code at least once so it writes its logs under ~/.claude. The extension reads them automatically — nothing to configure for the status bar, dashboard, and limits to populate.
3. Sign in to Claude Code (so your credentials exist — in ~/.claude/.credentials.json, or the login Keychain on macOS) for live, always-current plan limits; without it, the extension falls back to Claude Code's on-disk cache.
4. The status bar fills in on the next refresh. Click any segment, or run Claude Code Usage Tracker: Show Dashboard from the Command Palette, to open the dashboard. Predictive alerts are on by default — tune them under predictiveAlerts.*, or turn them off with predictiveAlerts.enabled.

Settings

Troubleshooting

The dashboard or status bar is empty. Claude Code has to have been installed and used at least once — the extension reads the JSONL transcripts it writes under ~/.claude/projects. If that folder doesn't exist or has no sessions yet, there's nothing to show.

Plan-limit bars don't appear. The 5-hour / weekly figures are fetched live from Anthropic using Claude Code's OAuth token (from ~/.claude/.credentials.json, or the login Keychain on macOS), falling back to ~/.claude/usage-cache.json. If neither is available, run Claude Code once (and sign in) so the credentials and cache exist. The status-bar segments also honor the showLimits setting and only appear while a limit window is live. Set useLiveApi to false to use the cache file only. With several editor windows open, the limits stay live in all of them: one window's fetch is shared with the rest, so no window gets rate-limited onto a stale "Updated _N_d ago" reading (no reload needed).

Extra usage (pay-as-you-go) doesn't show. It is off by default — turn on showExtraUsage. Even then it only appears when your Anthropic account actually has pay-as-you-go enabled (the API reports extra_usage.is_enabled); if your account has no extra usage, there is nothing to display.

Usage history is missing older days or months. Claude Code automatically deletes conversation logs older than cleanupPeriodDays (default 30 days), and once deleted they can't be recovered. To keep more history, add this to ~/.claude/settings.json:

{ "cleanupPeriodDays": 365 }

This only affects logs kept from now on; already-deleted sessions can't be restored.

Token counts look lower than your provider's dashboard. Tokens and cost are reconstructed from local logs and are an estimate. Sub-agents and background workflows write their own .jsonl files in sub-directories — the extension reads them, but some proxy setups don't record agent-level usage, so the totals here can run lower than the upstream count. Your real spend is always on your provider's billing page.

Numbers look stale. The extension refreshes when Claude Code writes to its logs, with a timer fallback (refreshIntervalSeconds). To force an update, run Claude Code Usage Tracker: Refresh from the Command Palette.

No forecast (→ 48%, · on pace, or · ~38m) shows next to a limit. The 5-hour pace meter appears once roughly a tenth of the window has elapsed (and the window isn't at 0% or already 100%); in the very first minutes you'll see just 5h 4%, because a projection divides by a small elapsed time and amplifies a single tick into an alarming number. The weekly ETA is shown only when you're on a trustworthy track to breach the weekly limit before it resets (its figure moves over days, so a constant readout would be noise) — the rest of the time it's just wk 9%, which is expected, not a missing reading. Turn either off with predictiveAlerts.showFiveHourEta / predictiveAlerts.showWeeklyEta, or the whole feature with predictiveAlerts.enabled.

The pace meter says · on pace instead of a percentage. That's deliberate. Within ten points of 100% the projection is a coin flip — at the window's midpoint a single percentage-point tick swings it about two points across the 100% line — so committing to → 104% would just be reversed on the next refresh. · on pace means you're tracking to use roughly all of the window and nothing more precise can honestly be said. Clearly under or over pace still shows the number (5h 23% → 45%, 5h 95% → 119%).

I'm not getting limit warnings. Warnings need predictiveAlerts.enabled on (the default). A threshold warning fires once when a window crosses each value in predictiveAlerts.warnThresholds (75% / 90% by default) and re-arms when the window resets — so if you've already crossed it this window, it won't fire again until reset. The predictive "you'll hit it before reset" warning needs predictiveAlerts.predictBreach on, and fires only once the window is at least half over, you're actively burning, and your projection is clear of the on-pace band — so a popup can never contradict a meter reading · on pace. (Notifications auto-dismiss; check the bell / Notifications center if you may have missed one.)

A "cheaper model" hint appeared, or I want one. That's the model-cost advisor, which is off by default. Turn it on with predictiveAlerts.modelAdvisor.enabled. It's deliberately rare — it only speaks up when recent turns show heavy spend on an expensive model for little output, at most once every few hours, and it has a Don't show again button.

"Explain with AI" asks for an API key — where do I get one? That button uses the Anthropic API (pay-as-you-go), which is separate from your Claude Code / claude.ai Pro/Max subscription — the subscription can't be used for it. Create a key at console.anthropic.com/settings/keys (Anthropic Console → Settings → API keys); it starts with sk-ant-. Running Set Anthropic API Key offers an Open Anthropic Console button that takes you there. The key is stored in VS Code Secret Storage and used only for this feature; each explanation is a single API call (cents on Sonnet) billed to that key. Clear it anytime with Clear Anthropic API Key. The rest of the extension — status bar, dashboard, limits, the local Advisor tips — needs no API key.

A subscription (Pro/Max) isn't enough for the API by itself — HTTP 400 "credit balance is too low". The Anthropic API is pay-as-you-go and separate from your Claude Code / claude.ai subscription and its session limits. Your sk-ant- key is valid, but its API account has no credit — a Pro/Max plan does not include API credit, and the subscription login can't be used to power third-party AI calls. Add a little credit at console.anthropic.com → Billing, then try again. (It's only cents per explanation.)

Development

npm install --include=dev   # install dev dependencies
npm run compile             # type-check + build to ./out
# then press F5 in VS Code / Cursor to launch the Extension Development Host

npm run watch keeps the compiler running while you work.

Changelog

See CHANGELOG.md for the full, dated history. The latest release brings back the always-on 5-hour pace meter: the previous release had hidden it for the first half of every window (and while idle), which read as a missing estimator. It now shows from early in the window, damped toward your current utilization at first so a thin early slice can't project an alarming number, and firming up to the plain projection by the half-mark. The breach popup still waits for a trustworthy, actively-burning track, and near 100% the meter still reads · on pace rather than a number that flips on the next refresh.

License

MIT — see LICENSE.