Claude Quota Bar

Your official Claude usage quota, always visible — on the Touch Bar or in the menu bar.

Shows your real 5-hour session and 7-day weekly utilization straight from Anthropic's usage API — the same numbers /usage shows in Claude Code — with a smart local fallback so the display never goes blank or silently stale.

━━━━━━ 47% · 2h   ━━━━━━ 8% · 6d

Why this and not another quota tool?

Every Claude quota tool faces the same choice:

Approach	Accuracy	Problem
Official API	exact	rate limited if polled too often → stuck/blank widgets
Local token counting (ccusage etc.)	estimate	can't see quota resets, model-specific weighting, plan changes

Claude Quota Bar does both. Official numbers are primary, polled conservatively (every 10 min) with exact Retry-After backoff so it can never spiral into a rate-limit loop. If the API is ever unavailable, it falls back to a local estimate computed from Claude Code's own transcript files — clearly marked with ~ so you always know which one you're looking at.

Features

• ✅ Official utilization % for the 5h session and 7d weekly windows, with reset countdowns
• ✅ Touch Bar support via MTMR — compact dual progress bars
• ✅ Menu bar support via SwiftBar / xbar
• ✅ Tap for details — macOS notification with exact percentages and reset times
• ✅ Rate-limit proof — honors Retry-After exactly, max 144 API calls/day
• ✅ Never stale — local ccusage --offline fallback (marked ~) when the API is down
• ✅ Zero config — reads your Claude Code OAuth token from the macOS Keychain

Requirements

• macOS, Claude Code installed and logged in
• jq — brew install jq
• ccusage (optional, enables the offline fallback) — npm i -g ccusage

Install

git clone https://github.com/Ractorrr/claude-quota-bar.git
cd claude-quota-bar
./install.sh

Touch Bar (MTMR)

1. brew install --cask mtmr
2. Open ~/Library/Application Support/MTMR/items.json and add the item from ~/.config/claude-quota/mtmr-button.json (generated by the installer with your paths)
3. MTMR reloads automatically — you should see the bars appear

Menu bar (SwiftBar)

1. brew install --cask swiftbar
2. ./install.sh swiftbar

For xbar, copy swiftbar/claude-quota.1m.sh into your xbar plugin folder instead.

Usage

Command	Output
claude-quota.sh	Touch Bar format — ANSI progress bars
claude-quota.sh menubar	SwiftBar/xbar plugin format
claude-quota.sh notify	macOS notification with full details
claude-quota.sh json	raw cached API response

Reading the display:

━━━━━━ 47% · 2h   ━━━━━━ 8% · 6d
   5h session %       7d weekly %
        time to reset      time to reset

A ~ prefix (e.g. ~47%) means you're seeing the local estimate — the API is temporarily unavailable and percentages are computed against your historical maximum usage instead of your real plan limits.

How it works

1. Token: read from the macOS Keychain entry Claude Code creates on login (Claude Code-credentials). Never written to disk or logs.
2. Fetch: GET https://api.anthropic.com/api/oauth/usage at most every 10 minutes. On HTTP 429 the exact Retry-After epoch is stored and respected — no retries, no spiral.
3. Fallback: if the official cache is missing or older than 2 hours, usage is estimated from Claude Code's local JSONL transcripts via ccusage --offline: current 5h block tokens vs your largest-ever block, and rolling 7-day tokens vs your busiest-ever week.
4. Cache: everything lives in ~/.cache/claude-quota/.

Uninstall

rm -rf ~/.config/claude-quota ~/.cache/claude-quota
# then remove the item from MTMR's items.json and/or the SwiftBar plugin

License

MIT