However you run Claude Code

Tokens, cost, messages and per-session context are read from the transcripts, which Claude Code writes the same way whichever way you start it — the terminal CLI, the Claude Code VS Code extension, or both at once. Every running session is listed, labelled by its project folder.

The 5-hour and weekly limit percentages come from Claude Code itself, which the extension asks in the background — using the copy of Claude Code that ships with its VS Code extension, or the CLI. Nothing to set up, and no terminal needed. See Real usage limits.

📊 Status Bar & Tooltip

The extension starts monitoring when VS Code opens. What the bar shows depends on whether it can read your real limits:

Reset: 02:13:20 | 5h: 6% | 7d: 35% | C: $31.34      Pro / Max subscription
Reset: 02:13:20 | 5h: … | 7d: … | C: $31.34         first reading in progress
Reset: 02:13:20 | C: $31.34 | T: 139.9k | M: 70     API key: no limits exist

Status Bar Components:

• Reset — countdown to the session reset (HH:MM:SS)
• 5h / 7d — percentage of the real 5-hour and weekly limits used (see Real usage limits)
• C — session cost, with /budget and a percentage if you set one
• T — tokens used (input + output), as a percentage if you set a budget
• M — messages, as a percentage if you set a budget

T and M are omitted while the real limits are shown, to keep the bar short.

Colour indicators apply to whichever signal is most reliable — the real limits first, otherwise your own budget:

• Neutral: below 60%
• Orange: 60-79%
• Red: 80% and above

Hover over the status bar for a tooltip with the usage limits, session timing, cost (session and last 7 days), token breakdown including cache, and burn rates.

🎨 Detailed Popup & Advanced Analytics

Click the status bar to open the statistics panel.

Session Timer — countdown to the reset, with the window's start and end times.

Usage Limits — three tiles with the real percentage consumed of the context window, the 5-hour window and the weekly window, each with its reset time, plus a per-session context list. See Real usage limits.

Token Usage, Cost Usage, Message Count — each section shows one bar:

• a progress bar with a percentage, when you have set a budget for that metric
• otherwise a composition bar showing what the value is made of — tokens by model, cost by model, messages by project — with a legend underneath

The composition bar exists because there is no honest denominator to divide by without a budget; it fills the same slot with real information instead of an invented percentage.

Advanced Analytics — the "More..." toggles expand each section:

• Token Components: input, output, cache creation (split by 5-minute and 1-hour writes) and cache read
• Burn Rates: tokens/min, $/min, messages/min
• Usage by Project: token distribution across your Claude projects
• Usage by Model: shown here when a token budget is set (otherwise it is already the composition bar above)

Real usage limits

Claude Code reports the actual percentage of your 5-hour and weekly limits you have consumed, together with the reset times. This is the only figure that answers "how close am I to being cut off" — token and cost counts cannot, because real consumption is weighted by model and effort level.

Nothing to turn on. The figures appear on their own shortly after VS Code starts — the first reading can take up to a minute, and the status bar shows 5h: … | 7d: … meanwhile. After that they refresh every two minutes.

What you get — three tiles in the popup, plus 5h and 7d segments in the status bar:

┌──────────────────┬──────────────────┬──────────────────┐
│     CONTEXT      │  5-HOUR WINDOW   │   7-DAY WINDOW   │
│       82%        │        6%        │       88%        │
│  PhotoManager    │  resets 14:35    │ resets Fri 20:01 │
│ ▁▁▁▁▁▁▁▁▁▁▁▁▁    │ ▁▁               │ ▁▁▁▁▁▁▁▁▁▁▁▁▁    │
└──────────────────┴──────────────────┴──────────────────┘

CONTEXT PER SESSION (4)
PhotoManager          82% · just now
claude-statusbar      66% · 1 min ago
Apokryf-Galicyjski    91% · 16 min ago
eBooki                 — · 2 h ago

Numbers are green below 60%, amber to 80%, red above. A value Claude Code does not report shows a dash — context is briefly absent right after /compact.

Context is per session, the limits are per account. The context window belongs to one conversation, so with several Claude Code sessions open there is no single "the" context: each is listed with its own percentage and how old that reading is (a session that has been idle stops reporting). The Context tile cycles through the open sessions every two seconds, naming the one it is showing, so the number never changes owner without saying so. A ~ marks a percentage the extension worked out from the transcript rather than one Claude Code reported. The 5-hour and weekly figures need no such split — they are account-wide and identical in every session.

How it works. The extension runs claude -p /usage in the background — the same local command as typing /usage in a Claude Code session — and reads what it prints. Claude Code answers with its own sign-in; the extension never reads or handles any credentials.

• No model is called, so it costs nothing and does not count against your limits. No session is recorded and your hooks are not run.
• The program is found without any setup: the copy bundled with the Claude Code VS Code extension (not on PATH, located through VS Code), or the CLI — on PATH or in the standard install locations.
• Several VS Code windows share one reading, so Claude Code is started once every two minutes however many windows are open.
• The output is text meant for people. The parser accepts the formats Claude Code uses and plausible variations (12- and 24-hour clocks, dates with or without a year, relative resets, ISO stamps, "left" instead of "used"). If a future version prints something it cannot read, the panel says so instead of showing empty tiles; the details go to the Claude Status Bar Debug output channel.
• If /usage ever stopped being a local command and reached the model, the extension detects the charge on the first call and stops asking that version.
• If Claude Code signs in with an API key, Amazon Bedrock or Google Cloud, there are no 5-hour or weekly windows at all — usage is billed per token. The section then says so, quoting Claude Code, and points you at the cost figures.
• Claude: Show Usage Limits Bridge Status reports which program was asked, when, and what it answered.

Optional: the status line bridge. Claude: Enable Real Usage Limits installs a small status line script that mirrors the numbers Claude Code hands to a status line command. It is no longer needed; it only adds second-by-second updates while a terminal session is open, and readings from both sources are merged. If you already use a status line, it keeps working — the bridge calls it with the same input. Claude: Disable Real Usage Limits removes the script and restores your previous status line.

⚙️ Configuration

VS Code Settings

{
  "claudeStatusBar.tokenBudget": 0,            // your token target; 0 = none
  "claudeStatusBar.costBudget": 0,             // your USD target;   0 = none
  "claudeStatusBar.messageBudget": 0,          // your message target; 0 = none
  "claudeStatusBar.refreshInterval": 5,        // 1-60 seconds
  "claudeStatusBar.showProjectName": false,    // project name in the panel header
  "claudeStatusBar.notifications.sessionEnded": true
}

Budgets are opt-in

No budgets are applied by default. Tokens, cost, and messages are shown as plain measured values, because Anthropic does not publish token or message quotas and there is nothing honest to divide by: real consumption is weighted by model and effort level, enforced over a 5-hour window plus weekly windows (Max plans have two — all models, and Sonnet only), and the 5-hour limits were doubled in May 2026. The real percentages come from Claude Code, as described above.

If you want a self-imposed pacing target, set one — the status bar then shows a percentage and warning colours against your number, and the popup switches that metric from a composition bar to a progress bar:

{
  "claudeStatusBar.tokenBudget": 200000,
  "claudeStatusBar.costBudget": 40,
  "claudeStatusBar.messageBudget": 500
}

Or run Claude: Set Budgets, which asks for all three. 0 (or an empty answer) means no budget for that metric.

Upgrading from 0.4.x or earlier: customTokenLimit, customCostLimit and customMessageLimit are migrated to the names above automatically, and are still read if the migration never ran. The claudeStatusBar.plan setting was removed — plan presets carried token limits Anthropic never published.

Installation

Via VS Code Extension Manager

1. Open VS Code
2. Go to Extensions (Ctrl+Shift+X / Cmd+Shift+X)
3. Search for "Claude Code Status Bar Monitor"
4. Click Install

Or visit the VS Code Marketplace page

Manual Installation

npm install
npx @vscode/vsce package          # runs the production build, emits the .vsix
code --install-extension claude-statusbar-*.vsix

Usage & Commands

Access via Command Palette (Ctrl+Shift+P / Cmd+Shift+P):

• Claude: Show Usage Details - Open detailed metrics popup
• Claude: Enable Real Usage Limits - Optional: add the status line bridge for live terminal updates
• Claude: Disable Real Usage Limits - Remove the bridge, restore your status line
• Claude: Show Usage Limits Bridge Status - Diagnose where the usage limits come from
• Claude: Set Budgets - Set your token, cost and message targets
• Claude: Refresh Usage Stats - Force refresh metrics

How It Works

Data Source

Claude Code stores conversation data locally in JSONL files:

• Windows: %USERPROFILE%\.claude\projects\
• macOS/Linux: ~/.claude/projects/ or ~/.config/claude/projects/

The extension monitors these files for changes and calculates metrics in real-time. Every entrypoint writes them identically, so a session started with claude in a terminal and one started from the Claude Code VS Code extension are measured the same way. Which sessions are currently open is read from Claude Code's own register in ~/.claude/sessions/, with the process checked, so a session that has ended drops off the list instead of lingering.

Session Windows

Claude Code uses 5-hour rolling sessions, plus weekly windows. The extension:

1. Detects your first message timestamp
2. Calculates session expiry (5 hours later) — or uses the reset time reported by Claude Code, as long as it is still in the future. A reported reset that has passed falls back to the locally computed window rather than declaring the session over
3. Tracks usage within the active window
4. Automatically resets when the session expires

Session windows are tracked on a rolling basis and are not cut at midnight, so a window that starts at 22:00 keeps its full history past the date boundary.

Only files modified within the last week are read, and parsed results are cached by modification time, so a large history does not cost CPU on every refresh.

Token Calculation

What counts toward limits:

• ✅ input_tokens - Your prompts
• ✅ output_tokens - Claude's responses

What doesn't count toward token limits:

• ❌ cache_creation_input_tokens - Cache overhead
• ❌ cache_read_input_tokens - Cache hits

Note: Cache tokens ARE included in cost calculations but NOT in token limits.

Cost Calculation

Costs use per-model published pricing (USD per million tokens), verified against Anthropic's pricing page on 2026-07-26. Note that pricing is per model version, not per family — Opus 4.5+ costs a third of what Opus 4.1 did:

Cache rates are fixed multipliers of the base input price: 1.25x for a 5-minute cache write, 2x for a 1-hour write, and 0.1x for a cache read. Claude Code writes 1-hour cache entries almost exclusively, so treating them as 5-minute writes understates cache cost by 37.5%.

Also accounted for:

• speed: "fast" — fast mode reprices Opus 5 / Opus 4.8 at $10/$50
• inference_geo: "us" — US-only inference applies a 1.1x multiplier
• Web search — $10 per 1,000 requests
• Model ids not in the table fall back to their family's rates and log a warning, so a newly released model is approximated rather than mispriced as Sonnet

Privacy

All data processing happens locally on your machine:

• ✅ No data sent to external servers
• ✅ No telemetry or analytics
• ✅ No account required
• ✅ Reads only your local Claude files
• ✅ Never reads or handles credentials — for the usage limits it runs Claude Code's own /usage command, and Claude Code contacts Anthropic with its own sign-in, exactly as when you type /usage yourself

Requirements

• VS Code: 1.104.0 or higher
• Claude Code: an active installation with local conversation data, run from a terminal, from the Claude Code VS Code extension, or both
• Node.js on PATH: required only for the optional status line bridge.
• Claude.ai Pro or Max: required for the 5-hour and weekly figures. They do not exist for API-key, Amazon Bedrock or Google Cloud sign-ins, where usage is billed per token and the cost figures are the relevant ones.

Development

Building

npm install
npm run compile

Watch Mode

npm run watch

Packaging

npm run package
vsce package

Testing

npm run test

Credits & Inspiration

This project was inspired by and built upon the excellent work of:

GUI & Architecture

• yahyashareef48/claude-usage-monitor - Visual design and VS Code extension architecture
  • Status bar layout and styling
  • Webview panel implementation
  • Real-time file watching approach

Calculation Logic & Accuracy

• Maciek-roboblog/Claude-Code-Usage-Monitor - Precise usage calculations
  • Token counting methodology (excluding cache tokens from limits)
  • Cost calculation formulas with model-specific pricing
  • 5-hour rolling session window logic
  • P90-based custom plan analysis

Note: This extension combines the best of both projects - accurate calculations from Maciek's monitor with the polished GUI from Yahya's extension.

License

MIT License - see LICENSE file for details.

Support

For issues or feature requests, please visit the GitHub repository.

Enjoy monitoring your Claude Code usage! 🚀