Disclaimer: Unofficial, community-built tool. Not affiliated with, endorsed by, or sponsored by Anthropic. "Claude" and "claude.ai" are trademarks of Anthropic, PBC.
100% vibecoded. This entire tool was written by Claude. The author takes no responsibility for anything — use at your own risk.
See your Claude rate limits in real time. Session percentage, reset timers, weekly usage, overage status. Works anywhere — terminal, status bar, scripts.
Reads your existing Claude Code OAuth token from macOS Keychain and makes a single 1-token API call to get rate limit data from response headers.
macOS (Apple Silicon):
curl -fsSL https://github.com/Dede98/claude-usage/releases/latest/download/claude-usage-darwin-arm64 \
-o /usr/local/bin/claude-usage && chmod +x /usr/local/bin/claude-usage
claude-usage install --daemonmacOS (Intel):
curl -fsSL https://github.com/Dede98/claude-usage/releases/latest/download/claude-usage-darwin-amd64 \
-o /usr/local/bin/claude-usage && chmod +x /usr/local/bin/claude-usage
claude-usage install --daemonLinux (amd64 / arm64):
curl -fsSL https://github.com/Dede98/claude-usage/releases/latest/download/claude-usage-linux-amd64 \
-o /usr/local/bin/claude-usage && chmod +x /usr/local/bin/claude-usageNote:
install --daemonuses macOS launchd. On Linux, runclaude-usage --daemon &or create a systemd unit manually.
Drop --daemon if you only want manual refresh:
claude-usage install- Reads your OAuth token from macOS Keychain (stored by Claude Code when you run
/login) - Makes a minimal API call (1 output token, Haiku) — costs ~$0.00025/day
- Parses
anthropic-ratelimit-unified-*response headers for real-time usage data - Writes to
~/.claude/usage-data.jsonfor other tools to consume
No scraping. No cookies. Just one authenticated API call that returns your limits in the response headers.
claude-usage # Ping API, show formatted output
claude-usage --json # Ping API, output JSON
claude-usage --watch # Live refresh every 60s
claude-usage --daemon # Background mode: ping + write to file
claude-usage --read # Display from cached file (no API call)
claude-usage --status # One-line summary for scriptingWatch a process and automatically pause it when rate limits get too high:
claude-usage guard --pid 12345 # Watch a specific PID
claude-usage guard --pid-file .gsd/auto.lock # Watch PID from lock file
claude-usage guard status # Show current usage + guard stateThe guard monitors both session (5h) and weekly (7d) limits, showing them side by side. When usage exceeds the threshold (default 80%), it sends SIGTERM to the watched process. When usage drops back down, it notifies you.
# Options
claude-usage guard --pid-file .gsd/auto.lock \
--threshold 90 # Pause at 90% (default: 80)
--warn 80 # Warn at 80% (default: threshold - 10)
--poll 15 # Poll every 15s (default: 30)
--auto-resume # Notify when safe to resume
--dry-run # Log actions without killing
--quiet # Suppress routine outputThe display updates in place — routine polls overwrite the same line, only state changes (warnings, pauses) get their own timestamped line.
Supports both plain PID files (12345) and JSON lock files ({"pid": 12345}) for compatibility with tools like GSD.
The install command automatically configures your Claude Code status bar:
██████████████░░░░░░ 67% session resets 2h 14m
If you already have a statusline configured, it wraps the existing one — nothing breaks.
To configure manually, add to ~/.claude/settings.json:
{
"statusLine": {
"type": "command",
"command": "claude-usage statusline"
}
}Or to wrap an existing statusline:
{
"statusLine": {
"type": "command",
"command": "claude-usage statusline --wrap \"node ~/.claude/hooks/my-statusline.js\""
}
}Colors change automatically: green (< 50%), yellow (< 80%), red (>= 80%). Weekly usage appears when >= 75%.
The install --daemon command sets up a launchd service for continuous polling:
# Manual daemon management
launchctl list com.claude-usage.daemon # Check status
launchctl unload ~/Library/LaunchAgents/com.claude-usage.daemon.plist # Stop
launchctl load ~/Library/LaunchAgents/com.claude-usage.daemon.plist # StartThe --status flag outputs a single line, useful for tmux, polybar, or other status bars:
$ claude-usage --status
session 67% weekly 31% [allowed] resets 2h14mThe tool writes ~/.claude/usage-data.json with this schema:
Key fields for integrations:
| Path | Type | Description |
|---|---|---|
version |
number |
Always 1. Check before parsing. |
timestamp |
number |
Unix ms. Data older than 5 min is stale. |
limits.five_hour.utilization_pct |
number |
Session usage 0-100% |
limits.five_hour.resets_at |
number |
Unix epoch seconds |
limits.seven_day.utilization_pct |
number |
Weekly usage 0-100% |
limits.status |
string |
Overall rate limit status |
limits.overage.status |
string |
Extra usage status |
auth.rate_limit_tier |
string |
Subscription tier |
error |
string|null |
Error if fetch failed |
The daemon writes a simple JSON file. That's your API. Build whatever you want on top of it — menu bar apps, Raycast extensions, Slack bots, dashboard widgets, IDE plugins, Home Assistant automations. Go wild.
See INTEGRATIONS.md for the full integration guide — JSON schema, code examples (Python, Node.js, Go, Swift, Bash), statusline wrapping, and ready-to-paste AI context. Paste it into Claude or any AI assistant and it has everything it needs to build your integration.
- macOS or Linux
- Claude Code installed and logged in (
claude /login) - macOS: reads OAuth token from Keychain automatically
- Linux: Keychain access requires
securityCLI (macOS only for now — Linux support for credential storage is planned)
It reads the OAuth access token that Claude Code stores in your macOS Keychain (service: Claude Code-credentials). No credentials are stored, copied, or transmitted by this tool — it reads from Keychain on every call and sends the token directly to api.anthropic.com.
The 1-token Haiku call exists only to trigger the API to return rate limit headers. The actual response content is discarded.
claude-usage uninstallThis stops the daemon, restores your original statusline, and removes the symlink. The data file (~/.claude/usage-data.json) is preserved.
git clone https://github.com/Dede98/claude-usage.git
cd claude-usage
go build -o claude-usage .
./claude-usage install --daemonMIT
{ "version": 1, "timestamp": 1711882800000, // Unix ms when fetched "source": "api", "auth": { "subscription_type": "team", // From keychain "rate_limit_tier": "default_claude_max_5x", "token_expires_at": 1774996245508 }, "limits": { "five_hour": { "utilization": 0.67, // 0.0-1.0 (raw) "utilization_pct": 67, // 0-100 (display) "resets_at": 1711890000, // Unix epoch seconds "resets_at_iso": "2026-03-31T17:00:00+00:00" }, "seven_day": { "utilization": 0.31, "utilization_pct": 31, "resets_at": 1712300000, "resets_at_iso": "2026-04-05T13:00:00+00:00" }, "overage": { "status": "allowed", // "allowed", "allowed_warning", "rejected" "utilization": 0.0 }, "status": "allowed", // Overall: "allowed", "allowed_warning", "rejected" "representative_claim": "five_hour", "fallback": "available" // "available" if model fallback exists }, "error": null // null or error string }