The Claude Code coach in your status bar. Not a billing tool. Not a multi-provider monitor. A focused token tracker that uses AI to help you use Claude Code better.
What this is: A VS Code status-bar monitor that reads your local Claude Code conversation logs and shows token-derived usage and cost estimates — plus an optional AI advisor that suggests how to improve your prompts and reduce waste.
What this is not: a billing tool. All amounts are estimates based on public per-million-token rates. Refer to your Anthropic account for actual charges.
看清你的 Claude Code 用量，让 AI 帮你用得更好。
简介：一个 VS Code 状态栏小工具，读取本地 Claude Code 对话日志， 按 token × 公开单价估算用量与成本；并提供可选的 AI 建议功能，帮你优化 提示词、减少不必要的 token 消耗。
它不是什么：账单工具。显示金额均为估算值，实际费用请以官方账单为准。
🌐 Multi-language documentation: English · 繁體中文 · 简体中文 · 日本語 · 한국어
Today's cost · current-session cost · 5-hour and weekly quota utilisation.
Hover the quota indicator for a breakdown:
Real /usage data — utilisation percent, reset countdown, and the
weekly reset weekday and time.
Click the status bar to open the full dashboard. Stacked token-composition chart, hourly breakdown, cache hit rate, cost composition by token type, plus per-model and per-day tables below.
Estimated breakdown of which content consumes tokens — your prompts vs.
tool results (by tool) vs. assistant output / thinking. This is the lever
for optimising your usage. Scoped to the last 30 days
(advice.promptWindowDays).
AI advice writes you a Markdown document, so it reads better as text than as
a screenshot. Set a key (advice.apiKey), click Get AI advice (the ✨ button
or the card on the Content tab), pick a scope (all projects, or one), and it sends
your usage aggregates + a sample of your own prompts to your model and opens a
prioritised report. Bring your own key — Anthropic (/v1/messages) by default, or
any OpenAI-compatible endpoint.
A flavour of what it returns (illustrative):
Write more complete instructions
- Several prompts open with "fix the bug" but don't name the file or the symptom, so the first turn is spent searching. Lead with the file + expected vs. actual behaviour.
Cut waste where it doesn't cost clarity
- ~38% of your tokens are spent above 150k context.
/clearbetween unrelated tasks keeps each request cheaper.
Paste a rough, half-formed request; get back one clean, paste-ready prompt (plain text, no Markdown) plus a recommended reasoning effort / thinking / model shown as chips. Three optional toggles refine it (flag vague references · condense long pastes · suggest a style direction). Experimental, off by default; only the text you paste is sent — never your files or the terminal — behind a one-time consent prompt.
- Sessions: resume / copy / delete — each row can copy the session id,
resume it (official Claude Code extension in-tab for this project, or a
terminal
claude --resume <id>for other projects), or delete it (to the trash, with confirm). A Current project / All filter defaults to the current project. - Quota display options —
quotaFiveHourOnly(show only the 5h window) andshowResetInStatusBar(append the reset countdown, e.g.5h:50%:2.3h | wk:30%:3.2d), both in ⚙ Settings. - Wider dashboard — detail page widened to 1600 px, still fluid on narrow screens.
- Workflows tab — every multi-agent run in one place: dynamic-workflow runs (ultracode) and ad-hoc sub-agent batches, with per-run cost, agent count, models used, cache hit rate (the "is my provider workflow-ready" diagnostic) and a per-agent drill-down labelled by each agent's task.
- Usage tracking panel — the official
/usage"what's contributing" view, but multi-provider and with five scopes (Day / Week / Month / session / project): >150k-context share, 8h+-session share, subagent-heavy share, workflow share, plus Skills / Subagents / Plugins / Models breakdowns. Compact card on the Today tab. - Thinking share per session (Sessions column + Today card) with an
/efforthint when it runs high. - Workflow quota guard — a dismissible banner before you start a run
the remaining 5-hour window can't finish
(
claudeCodeUsage.workflowQuotaWarnPercent). - Settings in the dashboard — a new ⚙ Settings tab manages every option
in place; VS Code's own Settings keeps only the three that benefit from
syncing (
language,dataDirectory,advice.apiKey). Header buttons trimmed to ✨ AI advice and ⚙ Settings (both jump to their tab); the auto-refresh toggle moved into Settings (a manual ↻ appears when paused). If you hide the cost, quota and context items, the status bar keeps a small icon as a way back into the dashboard. - Status-bar metric (
statusBarMetric) — keep showing today's cost, or switch the first item to today's total token count (compact k/M). - Weekly Opus limit (
showOpusWeekly, opt-in) — appendopus:NN%to the quota item for heavy Opus users. (PR #38, @wheelbarrel00.) - AI advice 2.0 — bring your own key: Anthropic (
/v1/messages) by default, or any OpenAI-compatible endpoint (advice.apiFormat). Fed with the new signals (runs, cache hit rates, attribution, thinking share); optionaladvice.userContextadds a "Personalised for this project" section;advice.promptWindowDays(default 30) sets the sampling window. Transport hardened: timeout, retry, curl fallback. (A keyless "subscription" backend was prototyped but isn't shipped — Anthropic blocks calling the API with the Claude Code OAuth token; it may return if that changes.) - Usage Optimizer (experimental,
advice.optimizer.enabled, default off) — a Content-tab card where you paste a rough request and get back one tightened prompt as plain text (paste-ready, no Markdown) plus a recommended effort / thinking / model. Three optional lenses (flag ambiguous references · condense long pastes · suggest a style direction). Only the text you paste is sent, behind a one-time consent prompt. - Context-window indicator (experimental, off by default) — opt in via
Settings to show the current session's context fill in the status bar. A "~"
marks a guessed window; set
contextWindowOverridefor proxied/custom models.
- Real 5-hour and weekly quota in the status bar — reads Claude Code's
existing OAuth session from
~/.claude/.credentials.jsonor the macOS Keychain, zero config. Adapted from upstream PR #9 by @Dobidop. - Four new tabs: Sessions, Projects, Content, Branches — all sortable.
- Token-composition stacked chart with Y-axis and reference lines.
- AI advice command (DeepSeek V4 Pro default,
reasoning_effort=max) with a demo-mode fallback when no API key is configured. - Multi-vendor pricing: Opus 4.x, Sonnet 4.x, Haiku 4.5 (verified
against Anthropic's public pricing); reference rates for proxied setups
(OpenAI, Gemini, DeepSeek, Kimi, GLM, Qwen) with family-aware fallback.
Refresh Token Pricingpulls live LiteLLM data as runtime overrides. - Custom timezone for date display (
claudeCodeUsage.timezone). - Light-theme tab readability fixed.
- Locale-aware numbers and dates throughout (German
., English,). - Real-time status bar via
fs.watch(1.5 s debounce) + idle-aware refresh + non-blocking loader (yields every 25 files).
Full changelog: CHANGELOG.md. Closes upstream issues #7, #10, #11, #13.
Search for Claude Code Usage in the Extensions view (Ctrl+Shift+X),
or:
ext install GrowthJack.claude-code-usage
Same extension is published at the Open VSX Registry: GrowthJack.claude-code-usage.
Ctrl+Shift+P → Extensions: Install from VSIX... → pick the
downloaded .vsix.
Most settings live in the dashboard now. Open the dashboard (run Show Usage Details, or click the ⚙ in its header) and use the ⚙ Settings tab — grouped into General, Status bar, Data & refresh, and AI advice & Optimizer. Changes apply immediately.
To keep VS Code's own Settings UI uncluttered, only three settings stay there
(so they still travel with Settings Sync). Open Settings (Ctrl+,) and search
for Claude Code Usage:
| Setting | Default | What it does |
|---|---|---|
language |
"auto" |
UI language: auto / en / zh-TW / zh-CN / ja / ko. |
dataDirectory |
"" |
Custom Claude data dir; empty = auto-detect. |
advice.apiKey |
"" |
API key for AI advice + the Usage Optimizer (empty = advice opens a demo instead). |
Everything else — refresh interval, status-bar items, number/date formatting,
project grouping, content analysis, and all the AI advice / Optimizer options —
is in the dashboard's ⚙ Settings tab. Upgrading keeps your existing values: a
one-time migration copies them out of settings.json on first launch.
The status-bar cost is Σ (tokens × per-million rate) across input,
output, cache-write and cache-read, summed by model.
- Per-million rates come from the bundled pricing table, which is verified against the public Anthropic pricing page and supplemented with reference rates for non-Anthropic models that may appear in proxied setups.
Refresh Model Pricing(command + button in the dashboard) pulls live prices from LiteLLM's public dataset as runtime overrides.- Unknown model snapshots are priced against the current tier of their detected family (Opus / Sonnet / Haiku / GPT / Gemini / DeepSeek / Kimi / GLM / Qwen) instead of falling back blindly.
What the status bar does not know:
- Your actual Anthropic invoice (discounts, free credits, plan caps).
- Whether your proxy provider charges different rates.
- Anything not recorded in your local
.jsonllog files.
The 5h / weekly quota indicator is different — it queries Claude
Code's real /usage endpoint via the OAuth session and shows the actual
percentage Anthropic is tracking for your account. That number is
authoritative.
- All token / cost / session analysis runs locally by reading your
~/.claude/projects/**/*.jsonlfiles. - The quota indicator calls
api.anthropic.com/api/oauth/usageusing Claude Code's existing OAuth token. No additional credentials are sent. - AI advice and the Usage Optimizer are the only features that call a
model — and only when you trigger them. AI advice sends an aggregate
summary of your usage plus a sample of your recent prompts; the Optimizer
sends only the text you paste into it (never your files or the terminal),
behind a one-time consent prompt. Both send to the endpoint in
advice.apiUrlwith your ownadvice.apiKey(Anthropic/v1/messagesby default, or any OpenAI-compatible endpoint). Bring your own key; nothing is shipped with the extension.
"No Claude Code Data"
- Make sure Claude Code is installed and you have used it at least once.
- Check the
dataDirectorysetting; auto-detection looks at~/.claude/projectsand~/.config/claude/projects.
Quota row shows 5h:--% wk:--%
- Claude Code's OAuth token is missing or expired. Log in to Claude Code
once; the extension reads
~/.claude/.credentials.jsonwhere present, or the macOS Keychain entry used by Claude Code, and refreshes the bearer if needed.
Get AI Usage Advice returns 404
- DeepSeek's current endpoint does not use a
/v1prefix. Usehttps://api.deepseek.com/chat/completions. The extension auto-strips/v1if present.
Get AI Usage Advice shows demo instead of real advice
- AI advice needs a key. With no key under
claudeCodeUsage.advice.apiKey, the command opens a hand-written demo (filename-marked…-DEMO-…, with a prominent banner) instead of calling any API. Add a key in Settings to get real advice.
Sluggish refresh on large histories
- 2.0 yields to the event loop every 25 files; idle ticks skip recompute.
If you still hit issues, raise
refreshIntervalor setenableContentAnalysistofalse.
Usage history disappears or is missing older months
- Claude Code automatically deletes conversation logs older than
cleanupPeriodDays(default: 30 days). Once deleted, those records cannot be recovered. To retain more history, add this to your~/.claude/settings.json:This only affects logs kept from now on; already-deleted logs cannot be restored. Thanks to @nickearnshaw for documenting this (PR #21).{ "cleanupPeriodDays": 365 }
Token counts appear lower than the model provider's own dashboard
- If you use Claude Code with a third-party proxy that routes requests
through sub-agents or background workflows (e.g. ultracode / dynamic
workflows), each agent writes its own
.jsonllog file inside a sub-directory. The extension reads all these files, but some proxy configurations may not write agent-level records at all. Until native workflow attribution is added in a future release, the total shown here may be lower than the provider's upstream count. Your actual spend is always on your provider's billing page.
Maintained by @Carl723000, who forked it
from @jack21's original
ClaudeCodeUsage and now also helps own and
maintain the upstream organization
ClaudeCodeUsage/ClaudeCodeUsage.
MIT-licensed. The 2.x work documented here (everything under "What's new") is by
@Carl723000 with Claude Code; it has grown well
beyond the 2.0 baseline — see CHANGELOG.md.
Contributors whose upstream PRs / issues are incorporated here:
- @Dobidop —
PR #9, the OAuth
approach for reading real
/usagedata; the quota indicator is adapted from that work. - @nickearnshaw —
PR #8 locale-aware
number/date formatting;
PR #20 fix for
the webview/status-bar getting stuck on "Loading…" (re-entrancy guard +
spinner only on cold start);
PR #21 docs on
cleanupPeriodDaysfor retaining usage history; PR #24 quota-window rollover handling (drop a window once its reset has passed). - @ScherbakovAl —
PR #31, the
original status-bar context-window indicator and the
showCosttoggle. - @wheelbarrel00 —
PR #38, the opt-in
weekly Opus limit (
showOpusWeekly) in the status bar. - @brenoneill — PR #14, custom data directory (merged into upstream 1.0.8).
- @mxzinke — Opus 4.5 / Haiku 4.5 prices
- German translation (upstream 1.0.8).
Also closed along the way: the test-suite seed (#25) and unreliable context-window detection for proxied/custom models (#31).
Many code changes in this fork were drafted with assistance from
Claude Code (commits include
Co-Authored-By: Claude <[email protected]>).
The current changelog lives in CHANGELOG.md. The most recent 2.1 entry summarises every feature, fix and personalisation option in this release.
Pre-2.0 history (upstream 1.0.x)
- Converted code comments from Traditional Chinese to English.
- Improved internationalisation standards.
- Pricing: added Opus 4.5 / Haiku 4.5 (thanks @mxzinke).
- Added German (de-DE) translation (thanks @mxzinke).
- Multilingual translation for hourly usage labels.
- Removed hardcoded Chinese text; switched to i18n.
- Added support for Claude Opus 4.1 pricing.
- Hourly usage statistics + visualisation.
- All-time data calculation; "All Time" translations.
- Repository URL migration + README image link fixes.
- Initial complete release.
Issues and pull requests are welcome on the GitHub repository.