Track Claude Code and OpenAI Codex usage locally in VS Code. See today's tokens in the status bar, remaining quota, cache usage, project and session trends, and optional usage advice in one dashboard. Install from the VS Code Marketplace or Open VSX.
The extension reads local provider logs. Processed Codex tokens include input and output; uncached usage excludes cached input, and quota is the last local observation, not a live account balance. Claude costs and Codex API-equivalent prices are estimates, not bills or subscription charges. Provider accounts remain the source of truth for billing. The 简体中文说明 covers the same features in detail.
Open the dashboard by clicking either usage indicator in the VS Code status bar. See features, privacy, installation, and contributors below.
🌐 Multi-language documentation: English · Deutsch · 繁體中文 · 简体中文 · 日本語 · 한국어 · Português (Brasil) · Bahasa Indonesia
- Claude Code and Codex, side by side: provider-specific Today, Last 30 days, All time, Sessions, and Projects views; Compare keeps their accounting separate.
- Know what used tokens: input, cached input, uncached usage, output, models, effort, and month → day → hour drill-down without rereading logs on chart clicks.
- See quota without confusing it with spend: Claude's official
/usageutilisation and Codex's last-observed remaining allowance; estimates are labelled. - Keep sharing under your control: preview and export local SVG/Markdown; sharing is on by default but can be disabled, and GitHub publication is separate.
- Local first: source logs stay provider-owned; optional AI advice requires an explicit request preview and separate Send action.
Show five historical dashboard previews (v2.3.1–v2.3.2)
The five v2.3 images below are reproducible captures of the production dashboard renderer with synthetic fixtures and VS Code Light+/Dark+ theme variables, not personal usage or billing evidence. Native VSIX installation is verified separately.
Today and Last 30 days share the configured calendar timezone. CLI usage is counted only when normal persistent sessions leave usage-bearing local logs; calls made without session persistence cannot be reconstructed.
The corrected Codex overview uses one configured-timezone calendar model for Today, Last 30 days, months, models, effort, and all-time totals.
Observed quota windows retain reset evidence locally. A valid used fraction can produce labelled total and unused subscription-durability estimates, including for the current window. Approximate evidence remains visible with low confidence. Period details start collapsed; expand them to inspect the numeric evidence.
Compare combines provider daily activity without double-counting Codex cached input or reasoning. Its preview-first share studio offers an Academic Violet default, curated/custom colors, deterministic local SVG, and privacy-safe Markdown. It is enabled by default and can be hidden with the single sharing workspace setting. Card settings sit below the preview; intensity can use quantile, logarithmic, or linear scaling. The metric is activity volume, not productivity or billing.
Projects now adds a Token-only 30/90-day project × day heatmap and stacked daily trend for both providers. Exact tooltips, explicit coverage, bounded rows, and an Other-projects tail keep the view auditable without rereading source logs.
Codex uses a compact Today token usage item and a separate remaining quota
item: observed 36% weekly utilisation displays wk 64%. The hover card retains
utilisation progress bars, reset times, and wrapped explanations. Local Codex
quota is last-observed evidence, not a live account balance.
Today's cost · current-session cost · 5-hour and weekly quota utilisation.
Hover the quota indicator for a breakdown:
Real /usage data: utilisation percent, plus time left and the wall-clock reset for every window.
Every weekly cap your plan meters gets its own row, per-model ones included (Anthropic supplies the name, so the row follows whichever model is capped), plus usage credits when you have them enabled.
⚙ Settings offers a compact quota-format dropdown: Built-in (default), 5-hour only, Weekly only, or Custom. Only Custom reveals the template field.
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).
v2.3 keeps one readable path from a local observation to its evidence, recommendation, action, feedback, and guarded result. It is off by default. Local evidence appears before any model is involved; Helpful, Not helpful, and Applied stay on this device. Once enough reliable, similar before/after tasks exist, the card reports the frozen comparison result; otherwise it says that the evidence is insufficient.
Each recommendation can be snoozed for a bounded period; it leaves the default summary and returns after expiry or when you choose to show it again.
AI personalisation is a separate choice. Aggregate-only is the default and prompt samples remain off until separately allowed. The extension prepares the complete request once and shows its exact JSON, byte count, and SHA-256. Preview sends nothing; Send this exact request is a second explicit action, using the same canonical bytes and your own configured key/endpoint. Claude Code OAuth credentials are never used as a generative backend.
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 included — never your files or the terminal. It now uses the same full-request preview and separate explicit Send action as AI advice.
Production renderer with synthetic usage and VS Code theme variables, not a real account or an installed-VSIX capture.
Current release · status bar, smooth scrolling, and one sharing workspace
- Bounded pricing diagnostics — unknown-model warnings are deduplicated and capped for each Extension Host lifetime, removing the per-record warning flood reported in #122. Already-expired content-analysis files retain their empty contribution rather than disrupting live-tail refreshes.
- Current model prices — dedicated Standard/cache rates for Opus 5.5, Sonnet 5.5, GPT-6.1 Sol, GPT-6 Sol and GPT-6 Luna. Unknown Codex IDs remain unpriced; family fallback estimates are not promoted to exact-price coverage.
- Defensive refreshes — malformed model metadata no longer aborts a whole index. Unsafe object keys cannot mutate shared prototypes; aggregate buckets are copied once per update, worker results have a bounded apply window, and manual price refreshes have byte, catalog-size, concurrency and time limits.
- Less disruptive dashboard updates — pausing auto-refresh freezes both provider pages, not background indexing or the status bar. Manual refresh remains available; failures retain verified data and show a compact recovery message. Primary-log coverage, hourly backfill and retry waits are separate. Completed Codex history stays quiet during normal appends/new files; identity ambiguity remains a quality warning, not a repeating backfill attempt. Unchanged hidden panels and weekly usage aggregates reuse bounded caches.
- Predictable preview and settings — AI previews show the actual endpoint, protocol and model; incompatible settings fail without redirecting to another host. Share Card export writes the accepted SVG and requires a new preview after control changes. Ordinary defaults reset preserves the API key, and the Codex directory remains editable even when provider detection fails.
- Large-history refreshes — unchanged Content attribution reuses its data without freezing AI controls. Display settings no longer restart completed cold reads, and late index results cannot restore superseded prices. Today attribution is cached by calendar day: unchanged minute-spaced polls update countdowns without rescanning the full history within the hour. The hourly hidden-panel refresh still recomputes Content attribution once.
- Upgrade safety — unchanged polls retain accepted sharing previews; changing the Claude data directory clears the old source even while updates are paused. Existing API keys without an explicit protocol retain the prior Anthropic format. If preview reports a mismatch, choose the intended API format and URL in Settings, then preview again before sending. Upgrade/default reset never silently reroutes that key to the new DeepSeek default; new installs use the matching OpenAI-compatible format.
- Codex status and scrolling — the default compact Token item shows today's processed amount; the separate weekly indicator shows remaining capacity. Live panel updates wait briefly for scrolling to pause, with a bounded delay.
- One preview-first sharing workspace — a full-width export preview now leads the surface, with controls below it and one presentation selector for the Combined activity heatmap, Claude Share Card, and Claude token heatmap. The combined presentation appears only with real data from both providers; both legacy presentations remain Claude-only.
- Compatibility without duplicate panels —
exportShareCard,exportHeatmap, andpublishHeatmapToGitHubremain available and open the matching presentation instead of bypassing preview.enableShareCardremains the single visible sharing switch and still defaults to on; the retiredshowHeatmapvalue is retained only for one-release state compatibility and bounded clearing. - Strict local-artifact boundary and provider truth — switching, previewing, and local SVG/Markdown export use materialized aggregates only and perform no network request, GitHub sign-in, or profile/avatar/name lookup. Only the separate Publish to GitHub action for the Claude heatmap can connect; it remains public-repository-only and confirms the exact target and create/ overwrite action before writing. Combined activity is not billing, productivity, capability, or cross-provider equivalence.
Claude Share Card preview · 360 px dark-theme view. Both use synthetic fixtures, not a real account.
The 2.3 series introduced local Codex tracking, provider-aware comparisons, request-level token attribution, and shareable activity views. It later added model/pricing updates, the project activity matrix, and month → day → hour drill-down. See CHANGELOG.md for patch-by-patch details.
Read the v2.3 changes by area
- Refined throughout the v2.3 line — GPT-6 Astra and Fable 5.1 model metadata, optional AWS Bedrock pricing, a fixed-reference display-currency selector, a Token-only 30/90-day project activity matrix, complete month/day/hour drill-downs, state-preserving refresh, accessible charts, and lower watcher/title-index overhead. Patch-level details stay in the changelog and GitHub Releases.
- Codex Beta, enabled by default — usage records are discovered only from
sessions/**/*.jsonlandarchived_sessions/**/*.jsonl; credential, database, and unknown files stay excluded. Separately, the extension streams exactly$CODEX_HOME/session_index.jsonlto mapidtothread_namefor truthful thread titles. Absolute paths are redacted and titles stay memory-only. Usage-record JSONL lines are streamed and temporarily parsed only to extract allowlisted usage and structural metadata; prompt, response, command, and tool-argument fields are not inspected or used for analysis, and are never retained or persisted. Disable Codex at any time in Settings → Providers. - Codex-native metrics — processed = input + output; uncached usage = uncached input + output; cached input is a subset of input; reasoning is a subset of output. The overview also shows input cache hit rate as cached input / input. No Codex billing cost is shown. The first Codex summary card is a clearly labelled API-equivalent cost estimate for the selected scope; the All-time view also shows the weekly trend using the same pricing basis.
- Calendar-day Today and cost trends — Codex Today means the current day in your configured timezone and adds exact hourly API-equivalent cost beside a separate token-composition view. Daily and monthly primary charts default to API-equivalent cost while token composition stays separately visible. Only exact known-model prices contribute; unknown models remain unpriced and every row keeps pricing coverage visible. The schema-3-compatible hourly sidecar keeps sparse buckets for the rolling last 30 days, is checkpointed and resumable, evicts day 31, and serves date expansion with zero JSONL reads on click. Codex monthly charts and tables list months oldest-first.
- Request-level token attribution — valid
last_token_usagecomponents are preferred, while itstotal_tokensremains an active-context measurement, not request usage. A full numeric total-plus-last signature suppresses only proven replay; missing last snapshots fall back to cumulative lineage high-water. Upgrading triggers one automatic reindex, with the indexed subtotal still visible throughout the pass.
- Weekly allowance-value trend — Claude and Codex All-time / Compare views
calculate historical used equivalents directly from local token logs. The
newest valid official reset observation anchors one sequence of unique,
non-overlapping weekly periods, and each usage event belongs to exactly one
period; without a usable observation, usage-only rows fall back to
Monday-to-Monday UTC calendar weeks. A genuinely different quota series with
an overlapping, non-aligned future reset is a conflict; same-series observations
remain one series and may be shown as a low-confidence approximation. It cannot
create a second current period, and period ranges are shown separately from reset times. Codex usage is
stored in daily slices: when one crosses an official intraday reset, its tokens
are still counted once, the affected period is labelled a boundary
approximation. Codex's account-wide
codexobservations can decorate both historical and current buckets. If an observed reset drifts from the seven-day grid, the sample is mapped to the display period containing its observation time; file-source uncertainty, reset drift, and daily boundary crossings lower confidence and are labelled as approximate. File keys are not account identities, so eligible local files in one home are included together. A current period still uses the latest real observation for a low-confidence blended estimate when local quota series overlap. Ambiguous completed periods, or periods without a usable observation, remain usage-only rather than inventing an account split. Any coherent observed window—including the current one—can show total and unused durability estimates; attribution or boundary uncertainty lowers confidence instead of silently replacing the values with dashes. This display rule neither changes the index schema nor triggers a rebuild. Current official API rates are applied consistently across history. This is a proxy, not a bill or an official subscription price. The panel is enabled by default and can be hidden in Settings withshowWeeklyEquivalentValue.
- One dashboard render stack — switching to Codex keeps the established Today / Last 30 days / All time / Sessions / Projects / Content / Settings structure, relabelled where Codex semantics differ. The same render functions, HTML classes, charts, tables, spacing, and responsive rules are used for both providers. Claude and Codex time-series charts stay width-aligned while dense content scrolls within its own region; Codex recommendations use indexed 30-day structural evidence.
- Truthful names, no invented concepts — root tasks use the latest real thread title after path redaction. Child rows prefer their own real thread title; when it is missing, they use the reported nickname and display the parent/root title; if those are also missing, they receive a localized neutral fallback. Projects use the Git repository name or, outside Git, the directory basename. The Codex view does not manufacture Branches or Workflows that cannot be measured reliably.
- Claude / Codex / Compare modes — keep each provider's meaning intact. Compare shows input, output, and cache side by side; it never adds unrelated costs or quota windows together.
- Auditable time and coverage — rolling 7-day and 30-day totals use exact event-day slices in your configured timezone. During an incomplete migration or rebuild, every Codex card, table, project, session, recommendation, and status value is visibly an indexed subtotal; unverified legacy totals are excluded. Once a Codex home is detected, its provider tab appears immediately; the page shows exact indexed-file, percentage, and byte progress during the first build, while Compare waits until both providers have real data. After the first atomic checkpoint, the complete subtotal dashboard stays usable while indexing continues; progress never replaces its cards or tables. A selected Codex home is account-agnostic, so logs left by multiple sign-ins in that same home are combined. Local logs expose no reliable account identity, so limit cards remain last-observed and are never summed.
- Private, scalable local index — stores machine-salted pseudonymous keys; numeric and structural aggregates; and sanitized project, directory, agent, model, effort, role, time, and quality metadata. It never persists raw IDs, full paths or repository URLs, thread titles, or conversation bodies. A background worker scans large histories with a default 30-second watcher delay (Off / 10 / 30 / 60 / 120 / 300 seconds). A first-time index or incomplete legacy migration gets one bounded 64 GiB / 16,384-file-pass streaming ceiling; it does not reserve that amount of memory and remains cancellable and resumable. After convergence, background work returns to 128 MiB / 64 file passes and the always-visible Refresh action uses 2 GiB / 512 file passes. Unchanged warm refreshes still read zero usage-record JSONL body bytes.
- Provider-aware controls — the shared Settings tab shows only common and Codex-effective controls when Codex is selected. Codex collection and local Codex recommendations can each be disabled.
- Exact-version release notice — the upgrade message only describes the installed release. It is on by default and can be disabled in Settings.
Sharing, conversation viewer, and usage analysis
- Usage share card (opt-in,
enableShareCard) — a themed, configurable one-page SVG of your usage: pick a range × scope (overall / project / session) × which metrics to show, and a theme (Claude Classic / Cream / Aurora Dark / Auto). Preview and local export never fetch GitHub identity data. Self-contained and deterministic; no prompts, paths or ids ever leave your machine. Chinese locales use 万/亿 units. - Read-only conversation viewer (Sessions tab, on by default) — a "view" button re-opens a past session's prompts and Markdown-rendered answers so you can jog your memory without loading it back into the model's context (unlike resume). Thinking and tool traffic sit behind toggles; opens on the last rounds.
- Token heatmap (opt-in,
showHeatmap) — a GitHub-style yearly token heatmap on the All tab, plus Export / Publish to your GitHub profile as a self-contained SVG with a one-click Markdown embed. - Experimental insights (opt-in,
showInsights, Content tab) — labelled estimates from your local logs: a cache-churn bill ($ spent re-writing cache after model switches / idle gaps), cache warmth by model, big one-shot turns, your active hours, and skill ROI (output tokens returned per $). - Top-10 costliest messages (opt-in,
showCostliestMessages) — ranks single turns by cost, splitting a cache miss from a long answer, with the cache-hit rate and the time since the last turn. - Sessions "Active" column — estimated hands-on time per session (idle gaps capped at 1.5 h), far more meaningful than the raw first-to-last span.
- Cache-hit-rate column in the All-time (monthly) and This-month (daily) tables and their drill-downs, so cache efficiency is visible per row.
- Live-refresh delay (
fileWatchSeconds: Off / 1 / 2 / 5 / 10 / 20 / 30 s) replaces the on/off live-watch toggle; it only re-reads your local logs. - Timezone-aware bucketing — Today / day / month / hour totals all key off your configured IANA zone (full UTC-offset dropdown), so they agree with each other and the Anthropic console.
- "What's new" prompt after upgrades — a single dismissible nudge the first time you run a new major.minor version, so opt-in features stay discoverable.
- Fixes — Sonnet 5 reports a 1M context window (#50); 1-hour cache writes are priced at 2× base input when the log carries the split (#62); background windows refresh on focus instead of going stale (#55); the Timezone setting is a validated dropdown so a bad value can't crash the dashboard (#51); German (de-DE) and Brazilian Portuguese (pt-BR) are selectable everywhere.
Sessions, workflow analysis, dashboard settings, and AI advice
- 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 most options in place; VS Code's own Settings keeps the language and provider data directories. The advice API key is entered in the dashboard and stored in SecretStorage, not Settings Sync. 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). - Model-scoped weekly limit (
showScopedWeekly, opt-in) — adds the weekly cap actually named by Anthropic, such asfable 17%; migrated from the original model-specific contribution in PR #38 by @wheelbarrel00. - AI advice 2.0 — bring your own key for Anthropic or an OpenAI-compatible
endpoint (
advice.apiFormat). The v2.3 line places local evidence and an exact full- request preview before the separate Send action. Aggregate-only is the default; prompt samples andadvice.userContextrequire independent prompt- personalisation consent and appear verbatim in the preview. The keyless Claude Code subscription backend is not shipped and is unreachable. - 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 included, and the full provider request must be previewed and explicitly sent. - 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.
Official Claude quota, new tabs, pricing, and live status bar
- Real 5-hour and weekly quota in the status bar — reads the OAuth session
from the same Claude profile as the window: explicit
dataDirectory, then the first validCLAUDE_CONFIG_DIR, then~/.claude. The macOS Keychain is used only for the default profile. 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 — now routes to the unified local-evidence surface; a missing API key leaves the request unsent instead of opening a separate demo or transport path.
- 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 ordinary settings
stay there. The BYOK advice key is entered in the dashboard's ⚙ Settings tab
and stored in SecretStorage; it does not travel with Settings Sync. Open VS Code
Settings (Ctrl+,) and search
for Claude Code Usage:
| Setting | Default | What it does |
|---|---|---|
language |
"auto" |
UI language: auto / en / de-DE / zh-TW / zh-CN / ja / ko / pt-BR / id. |
dataDirectory |
"" |
Custom Claude data dir; empty = auto-detect. |
codex.dataDirectory |
"" |
Custom Codex home; empty = CODEX_HOME or ~/.codex. |
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.
For a custom quota status-bar layout, choose Custom in ⚙ Settings. The
template accepts {5h.pct}, {wk.pct} (or {7d.pct}), and
{model:Fable.pct}; each window also supports .label and .reset.
Reset styles include :decimal, :units, :clock, and :at, for example
{5h.pct} | {wk.reset:at}. Missing windows and their separators are omitted.
The built-in choice leaves the existing quota options unchanged.
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.
Claude transcript totals are counted by response identity, not by JSONL
row. One response can produce both a thinking row and a text row carrying
the same messageId, requestId, and complete usage vector. The extension
keeps the largest vector for that response once; Claude Code's stats-cache
adds the rows. The two totals can therefore differ.
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.
The complete user-facing inventory, retention rules, clearing behavior, and remote boundaries are in Local data and privacy (简体中文).
| Data | Stored locally | Remote behavior | Clear path |
|---|---|---|---|
| Claude/Codex source logs | Provider-owned and read-only; never copied wholesale | None by default | Managed by the provider tools, not deleted by this extension |
| Codex derived index | Bounded pseudonymous numeric/structural aggregates, isolated by source directory, profile salt and timezone | None | Rebuild the active index; Clear All removes every exact index family in this extension storage |
| Quota observations | Bounded anonymous window facts; no raw account ID | Claude quota fetch only when enabled; Codex evidence stays local | Clear by provider/account epoch or all |
| UI/share preferences | Tab/filter state plus optional title/range and GitHub destination strings | Publish only after exact explicit confirmation | Reset UI or sharing preferences independently |
| Advice data/key | Bounded aggregate evidence; key only in SecretStorage | Exact previewed request only after separate Send | Clear advice data and key independently |
A timezone switch can reuse a complete, proven same-source checkpoint read-only; only date/hour buckets migrate, without restarting primary history.
- All Claude token / cost / session analysis runs locally by reading your
~/.claude/projects/**/*.jsonlfiles. - Codex usage records are discovered only from
sessions/**/*.jsonlandarchived_sessions/**/*.jsonlbelow your Codex home. Separately, the extension streams exactly$CODEX_HOME/session_index.jsonlfor theid→thread_namemapping used by truthful thread titles. Absolute paths in those titles are redacted and the titles remain memory-only. Credentials, databases, and unknown files are not read. Usage-record JSONL lines are streamed and temporarily parsed only for allowlisted metadata; prompt, response, command, and tool-argument fields are not inspected or used for analysis and are never retained. Deterministic insights make no network request. - The Codex persistent index stores machine-salted pseudonymous keys, numeric and structural aggregates, and sanitized project, directory, agent, model, effort, role, time, and quality metadata. It never stores raw IDs, full paths or repository URLs, thread titles, or conversation bodies.
- The quota indicator calls
api.anthropic.com/api/oauth/usageusing Claude Code's existing OAuth token. If that token has expired, the extension sends the existing refresh token toconsole.anthropic.com/v1/oauth/tokenand writes the refreshed credentials back to the selected Claude credential file or macOS Keychain item. See Local data and privacy. - AI advice and the Usage Optimizer are the only features that call a
model — and only after you preview and explicitly send a prepared request.
Advice defaults to allowlisted aggregates; prompt samples and optional user
context require separate consent. The Optimizer includes only the text you
paste into it (never your files or terminal). Both use the exact previewed
bytes, the endpoint in
advice.apiUrl, and your ownadvice.apiKey. Bring your own key; no key or generative OAuth credential is shipped.
- A reset absent from an official response or local structured event cannot be reconstructed; day-only evidence lowers confidence.
- One Codex home may contain several sign-ins. The current period may therefore show a low-confidence blended estimate from the latest real observation; ambiguous completed periods remain used-only rather than inventing an account split.
- API-equivalent values depend on current known API prices and visible pricing coverage. They are not bills or subscription prices.
- Source-log retention belongs to Claude Code and Codex. Uninstall may leave host-managed extension storage behind, so the explicit clear controls are the reliable deletion route.
"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.
One-shot Claude CLI activity is missing
- Calls made with
--no-session-persistencecan leave a prompt-history entry but no project transcript and no tokenusagefields. The extension does not invent token or cost totals from prompt history. Run future audited calls without that flag if they should appear; past unpersisted token usage cannot be reconstructed locally.
Quota row shows 5h:--% wk:--%
- Claude Code's OAuth token is missing or expired. Log in to the active Claude
profile once. Credentials follow explicit
dataDirectory, then the first validCLAUDE_CONFIG_DIR, then~/.claude; the single global macOS Keychain item is never substituted for a selected custom profile.
Get AI Usage Advice returns 404
- Match the API format, address and model. For DeepSeek's OpenAI-compatible
format use
https://api.deepseek.com/chat/completions; its explicit Anthropic compatibility base ishttps://api.deepseek.com/anthropic(official documentation). The request preview shows the resolved destination; the extension does not silently switch providers or remove a configured proxy prefix.
Send this exact request is unavailable
- Enable the default-off advice-effectiveness setting, allow aggregate data,
and configure your own
claudeCodeUsage.advice.apiKey. Previewing is always local; without a key the request remains unsent.
High CPU or sluggish refresh on a large history (Linux included)
- V2.2.1 removes the hidden 8-second active polling override and bounds the first-timestamp scan. Until you install it, set Live refresh delay to Off, set Refresh interval to 300–900 seconds, and optionally turn Content analysis off. Turning Dashboard auto-refresh off by itself does not stop status-bar parsing.
- If V2.2.1 still runs hot, open Show Diagnostic Logs and attach only the
anonymous
refresh:lines to issue #70; they contain counts and timings, not prompts, paths, session IDs, credentials, or raw log lines.
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 are lower than Claude Code's stats-cache
- A single response can be written as separate
thinkingandtexttranscript rows with the samemessageId,requestId, and completeusagevector. The extension counts that response identity once and keeps its largest vector; Claude Code'sstats-cachesums the rows. The extension does not apply a multiplier to make these different mechanisms agree.
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.
Created by @jack21 and maintained by @Carl723000, with community PRs, issue reports, reviews, and translations. Thank you to everyone who helped shape the project. The lists below cover public PR and issue authors through v2.4.0; a linked PR is not a claim that every proposed line shipped. See CONTRIBUTING.md for the release-credit convention.
Merged PR authors and examples of their contributions
- @Alfiefe10 — quota format; test stability.
- @akapti — AWS Bedrock regional pricing.
- @Carl723000 — Claude/Codex dashboard; release and maintenance work.
- @Dobidop — OAuth usage limits.
- @e7d — Opus 5 context window.
- @henrique-carvalho-dev — Brazilian Portuguese.
- @jack21 — original project; Codex adaptation guidance.
- @jackieyangjq — dashboard date-label performance.
- @mxzinke — model pricing; German translation.
- @nickearnshaw — localization; loading/quota fixes; test, CI, and docs foundations (PRs).
- @oxsean — session actions and quota resilience.
- @PhisicsLollo0 — monthly cost in the status bar.
- @projectronic — reset countdown; Indonesian UI and timezones (PRs).
- @ptweezy — unreadable-log resilience.
- @rsyuzyov — incremental indexing and date-formatting performance (PRs).
- @ScherbakovAl — status-bar cost toggle and context fill.
- @UfukTanriverdi8 — Sonnet 5 context window.
- @wheelbarrel00 — model-scoped weekly quota.
- @YuboZhang — model pricing; daily date labels.
- @zeyutang — timezone/cache pricing; weekly quotas and credits tooltip (PRs).
Issue reporters (including issue-only contributors)
- @jordanvalnet — unknown-model warning flood and Windows OOM evidence.
- @dreamerhyde #1 · @skyprawngo #2 · @tjx666 #3
- @andrew-west-empromptu #7 · @faangbait #10 · @leisn #11 · @dmathisen #13
- @Rissew #17 · @zhaoxiao9302 #18, #105
- @danielboxer #26 · @lyrzxz #27 · @BarisKuzu #45, #87
- @ekimminau #51 · @dbookstaber #54 · @eduardogomezgvp #55 · @chuccv #70
- @nsevene #80 · @arhneu #82 · @jcastillooo #84
- @HoangJN #89 · @Bozodragon #91 · @aaroncvan #94 · @mkgaskin-ops #99
- PR authors also reported issues: @nickearnshaw #25, #33 · @oxsean #40 · @projectronic #74. The maintainer's own issues are in the issue history.
PR proposals not merged
Thanks also to @huanglune (#12), @brenoneill (#14), and @Ailuras (#28) for proposing changes. These PRs were closed without merge; their ideas are credited without claiming that the PR code shipped.
Development assistance: Claude Code and OpenAI Codex are credited separately from human contributors. The project is MIT-licensed.
See CHANGELOG.md and the versioned GitHub Releases for detailed change history and release-specific attribution.
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.