sonichi / quota-tracker

Quota Tracker

Monitor your Claude Code quota in real time by intercepting Anthropic API rate limit headers.

When to Use

• "How much quota do I have left?"
• "Am I close to the rate limit?"
• "When does my quota reset?"
• Before starting expensive tasks

How It Works

A credential proxy sits between Claude Code and the Anthropic API. It reads anthropic-ratelimit-unified-* headers from every API response and writes quota state to a JSON file.

Quick Check

# Read current quota state
cat quota-state.json

Output includes:

• anthropic-ratelimit-unified-5h-utilization — % of 5-hour window used
• anthropic-ratelimit-unified-7d-utilization — % of 7-day window used
• anthropic-ratelimit-unified-5h-reset — when the 5h window resets (epoch)
• anthropic-ratelimit-unified-7d-reset — when the 7d window resets (epoch)
• anthropic-ratelimit-unified-status — "allowed" or "rejected"

limit_state is allowed, overage or rejected. overage means a limit window is rejected but anthropic-ratelimit-unified-overage-status is allowed/allowed_warning and no 429 has landed since: the core is serving on extra usage, so available stays true. Clients read this field rather than re-deriving it from the headers; the rule is classify_limit_state in src/quota_availability.py.

recent_rejections is a bounded ledger (newest 20) of upstream responses the proxy forwarded with a 4xx/5xx other than 401 — {ts, status, path, snippet, model, user_agent, peer_port} — the proxy serves every seat on the host, so the client fields are what make a rejection attributable; the probe counts only entries for this core's own model (SUTANDO_CORE_MODEL or core-runtime.json) and counts every client when that is unknown. It survives the per-response header rewrite, and health-check.py's core-request-rejections probe warns on one inside 15 minutes and fails on five inside an hour, so a credits/overage rejection that leaves every unified-status header allowed still reaches the owner.

Setup

1. Start the credential proxy

npx tsx "$SKILL_DIR/scripts/credential-proxy.ts"

This starts on port 7846 and reads OAuth credentials from macOS keychain.

2. Route Claude Code through the proxy

ANTHROPIC_BASE_URL=http://localhost:7846 claude ...

Or add to your voice agent's launchd plist:

<key>ANTHROPIC_BASE_URL</key>
<string>http://localhost:7846</string>

3. Read quota state

python3 "$SKILL_DIR/scripts/read-quota.py"           # human readable
python3 "$SKILL_DIR/scripts/read-quota.py" --json     # machine readable
python3 "$SKILL_DIR/scripts/read-quota.py" --gate     # exit 1 if exhausted, not routed, OR stale

Requirements

• macOS (reads OAuth from keychain)
• Claude Code logged in (subscription or API key)
• Node.js with tsx