Why
Claude Code's 5-hour and weekly limits live behind the /usage command — you have to stop and ask. Claude Quota keeps them on screen all the time:
◆ 5h 29% · 7d 26% · 2h28m · $6586
5-hour limit · weekly limit · time until the 5h window resets · spend
The badge color tracks the higher of your two real utilizations — green, amber near the cap, red when you're about to hit it. Click it for the full panel above.
Features
- 🎯 Real numbers, not guesses. The 5h + weekly utilization and reset times come from Claude's own usage endpoint — they match the claude.ai site exactly, including the weekly limit.
- ⏱ Reset countdown for the 5-hour window, always visible.
- 📊 Mission-control panel — ring gauges for 5h + weekly, extra-usage credits, today/week/month spend, active-window telemetry, and a 7-day sparkline.
- 💸 Cost computed locally with
ccusage (notional API-equivalent — handy as a volume gauge). Cache tokens excluded from headline numbers.
- 🔌 Works offline too. If the usage API is unreachable, the reset is recomputed from your local transcripts (matches the site to ~1 min).
- 🔒 Private by design. No telemetry. The only network call is to Anthropic's own API, with your own token.
- 🎨 Theme-native. Adapts to any VSCode light/dark theme; respects reduced-motion.
Install
From the Marketplace (once published)
Search “Claude Quota” in the Extensions view, or:
ext install andrewaltair.claude-quota
From a .vsix
Grab the latest from Releases → Extensions view → ⋯ → Install from VSIX… → reload.
From source
git clone https://github.com/andrewaltair/CLAUDE_QUOTA.git
cd CLAUDE_QUOTA
npm install
npm run package # -> claude-quota-x.y.z.vsix
How it works
| Number |
Source |
Exact? |
| 5h % + reset, weekly % + reset, extra-usage |
Claude usage API (GET /api/oauth/usage) — same as /usage & the site |
✅ exact |
| Cost (today / week / month / window) |
local transcripts via ccusage |
≈ notional API-equivalent |
| Reset (fallback, API offline) |
local transcripts, no hour-rounding |
≈ ±1 min |
Your OAuth token is read locally from ~/.claude/.credentials.json and sent only to api.anthropic.com over HTTPS — never logged, never stored, never sent anywhere else. Prefer zero network? Set claudeQuota.useServerApi: false for a local-only estimate.
Settings
| Setting |
Default |
Description |
claudeQuota.useServerApi |
true |
Use Claude's usage API for the real reset/utilization. Off = local-only estimate (no token, no network). |
claudeQuota.costScope |
month |
Which $ shows on the badge: window · today · week · month. |
claudeQuota.refreshIntervalSeconds |
60 |
How often the badge refreshes (clock + cost, local). |
claudeQuota.usageApiIntervalSeconds |
180 |
How often the real limits are fetched. Kept slower than the badge because the endpoint is rate-limited; the % is cached and the clock keeps ticking between fetches. |
claudeQuota.claudeConfigDir |
(auto) |
Override ~/.claude (sets CLAUDE_CONFIG_DIR for ccusage). |
Commands (⇧⌘P / Ctrl+Shift+P): Claude Quota: Refresh Now · Open Details Panel · Set Cost Scope.
Requirements
- A logged-in Claude Code (
~/.claude/.credentials.json) for the real-API numbers — without it the badge falls back to the local estimate.
- Node.js on your PATH (used to run the bundled ccusage CLI for cost).
- Some usage history under
~/.claude/projects/.
FAQ
Does it cost me anything / count against my quota? No. The usage endpoint is a read; ccusage just parses local files.
Is the $ real money? No — Claude Max is a flat subscription. The $ is the API-equivalent value of your tokens, a useful load/volume gauge.
Why was an early build showing the wrong reset? Pure-local tools bucket messages into 5-hour blocks floored to the hour, which can be ~1h off. This extension reads the real reset from the API (with a no-floor local fallback), so it matches the site.
Privacy
No analytics, no third-party servers. One outbound request: Anthropic's /api/oauth/usage, authorized by the token Claude Code already stored on your machine. Turn it off entirely with useServerApi: false.
Contributing
PRs welcome — see CONTRIBUTING.md. Run npm run smoke to see the real numbers from your data without launching VSCode.
License
MIT © Andrew Altair
