Claude Code Usage Monitor

CLI dashboard + GNOME Shell extension for monitoring Claude Code usage — utilization percentages, rate-limit reset times, token counts, and estimated costs.

How it works

Claude Code has no public usage API. This tool polls the Anthropic API with a minimal 1-token Haiku request (~$0.000012/poll) and reads the rate-limit headers to determine your current utilization. Token and cost data is parsed from Claude Code's local JSONL conversation logs.

Features

• CLI dashboard — colored tables showing utilization, tokens, and costs across configurable time periods
• GNOME Shell extension — panel indicator with current (5h) and weekly (7d) utilization percentages, with detailed stats in dropdown menu
• Minimal polling cost — ~$0.017/day, ~$0.52/month with 60s interval
• Single static binary — no runtime dependencies, no Python, no venv
• Configurable — YAML config for polling interval, display periods, cost visibility, color thresholds, model pricing overrides

Requirements

• Go 1.23+ (build only)
• Claude Code with valid credentials at ~/.claude/.credentials.json
• GNOME Shell 45–50 (for the extension)

Installation

Build and install everything

make install

This builds the binary, installs it to ~/.local/bin/claude-usage, and copies the GNOME Shell extension.

Binary only

make install-binary

Extension only

make install-gnome-extension
gnome-extensions enable claude-usage@claude-code-usage

Note: On Wayland, you must log out and back in (or use a nested shell) for extension changes to take effect.

Usage

CLI

# Full dashboard with polling
claude-usage

# Skip polling, use cached data
claude-usage --no-poll

# Force poll even if cache is fresh
claude-usage --force-poll

# Hide cost estimates
claude-usage --no-cost

# Show specific period only (today, 7d, 30d, all)
claude-usage --period 7d

# Poll and update cache silently (for scripting/cron)
claude-usage --poll-only

# JSON status output (used by GNOME extension and other consumers)
claude-usage --status

# Force a fresh API poll with status output
claude-usage --status --force-poll

# Cache-only status, no API call (returns stale data if cache exists)
claude-usage --status --no-poll

# Use custom config file
claude-usage --config /path/to/config.yaml

GNOME Shell extension

Once enabled, the extension shows a panel indicator:

C:42%  W:67%

• C — Current period (5h window) utilization
• W — Weekly period (7d window) utilization
• Color-coded: green (<80%), orange (80–89%), red (>=90%)
• Faded to 50% opacity when Claude Code is not running
• Labels dimmed at 50% opacity when data is stale
• Click for a dropdown with:
  • Current/Weekly stats with reset times (same colors as panel)
  • Stale data warning (orange) when applicable
  • Claude Code process state: running (green) / not running (orange)
  • Auth state when not valid: expired (orange) / missing (red)
  • "Refresh Now" button
  • Disclaimer noting data is estimated
• Calls claude-usage --status every 30s; all logic lives in the CLI
• "Refresh Now" uses --status --force-poll to trigger an API call
• Binary lookup: checks $PATH first, falls back to ~/.local/bin/claude-usage

Configuration

Default config location: ~/.config/claude-code-usage/config.yaml

See config.default.yaml for all options:

api:
  enabled: true
  stale_after: 60 # seconds — poll API if cache is older than this
  model: claude-haiku-4-5-20251001
  only_when_active: true # only poll when Claude Code is running

display:
  show_cost: true
  periods:
    - today
    - 7d
    - 30d

colors:
  green_below: 80 # percentage thresholds
  orange_below: 90

cache:
  # path: /custom/path/quota.json  # default: ~/.cache/claude-code-usage/quota.json

Testing the extension

Requires mutter-devkit package (Arch: mutter):

make test-gnome-extension

This installs the extension and launches a nested GNOME Shell via dbus-run-session gnome-shell --devkit --wayland.

Uninstall

make uninstall

How polling works

1. Sends a minimal API request: max_tokens: 1, content: ".", temperature: 0 using claude-haiku-4-5-20251001
2. Reads x-ratelimit-* response headers for utilization and reset times
3. Writes results to a JSON cache at ~/.cache/claude-code-usage/quota.json
4. GNOME extension calls claude-usage --status every 30s, which returns JSON with raw data (percentages, reset times, colors, stale flag)
5. The CLI handles cache freshness internally — if cache is warm, it returns cached data without polling
6. The extension is a pure renderer — it formats display text and handles the stale indicator locally

Cost note

Cost values shown are API-equivalent estimates based on token counts and published pricing. If you're on a Claude subscription (Pro/Team/Enterprise), usage is included in your plan — the costs shown represent what the equivalent API usage would cost, not actual charges.

License

GPL-3.0