CC Usage Monitor — Desktop Widget

A lightweight, borderless floating widget that monitors your Claude Code (Anthropic) session usage in real time.

Available for Windows and macOS.

---

What it shows

┌─────────────────────────────────┐
│ ◆ CLAUDE CODE          54%      │
├─────────────────────────────────┤
│ SESSION  5h                     │
│  54%              IN    1.2k    │
│ ██████████░░░░░░      OUT  340  │
│  54%  API ✓         ⟳ 3h 12m  │
├─────────────────────────────────┤
│ WEEK  7d   ⟳ 6d 4h             │
│   8%              IN    4.1k   │
│                       OUT  980  │
├─────────────────────────────────┤
│ EXTRA  0%  ● allowed  ⟳ 13d 6h │
├─────────────────────────────────┤
│ ● allowed                2m ago │
└─────────────────────────────────┘

Element	Meaning
Session %	5h rolling usage, green / yellow / red
Progress bar	Visual fill with 90% warning marker
⟳ countdown	Time until session resets
IN / OUT	Session token counts (from JSONL, no extra API calls)
WEEK 7d	Weekly usage % + days to weekly reset
EXTRA	Extra usage (overage) % in the current billing cycle + days to billing reset
● status	allowed · soft_limited (yellow) · hard_limited (red)
Xs ago	Time since last Claude Code activity

The system tray icon shows the session % at a glance, colored by status.

---

Requirements

• Python 3.8+
• Claude Code installed and signed in (manages the OAuth token automatically)
• Optional (for tray icon): pystray + Pillow

Windows

• Windows 10 or 11

macOS

• macOS 10.15 (Catalina) or later
• Python 3 via Homebrew: brew install python
• pystray tray icon requires pystray ≥ 0.19.0 (run_detached support)

---

Installation

pip install pystray pillow

Without pystray / Pillow the widget still works — just no system tray icon.

---

Usage

Windows

windows\start_widget.bat        ← double-click (no console)
python windows\claude_widget.py ← with console (for debugging)

macOS

sh mac/start_widget.sh          # background, no terminal
python3 mac/claude_widget.py    # with terminal

The widget appears bottom-right on Windows and top-right on macOS (below the menu bar).

---

Interaction

Action	Result
Drag title bar	Move the widget
Double-click	Toggle compact mode (title bar only)
Right-click	Context menu
Esc	Quit

Context menu: Refresh API · Toggle compact · Pin/Unpin · Hide to tray · Open .claude/ · Quit

---

How it works

Every 5 minutes the widget makes one minimal API call (Haiku model, 1 token) and reads official Anthropic rate-limit headers:

Header	Meaning
anthropic-ratelimit-unified-5h-utilization	Session usage 0–1
anthropic-ratelimit-unified-5h-reset	Session reset timestamp
anthropic-ratelimit-unified-5h-status	allowed / soft_limited / hard_limited
anthropic-ratelimit-unified-7d-utilization	Weekly usage 0–1
anthropic-ratelimit-unified-7d-reset	Weekly reset timestamp
anthropic-ratelimit-unified-overage-utilization	Extra usage consumed 0–1
anthropic-ratelimit-unified-overage-reset	Billing cycle reset timestamp
anthropic-ratelimit-unified-overage-status	Overage status

Token counts (IN/OUT) are read from ~/.claude/projects/**/*.jsonl every 5 seconds — no API calls.

Why not parse JSONL for the % ? With a Pro subscription costUSD = 0, and cache_read_input_tokens causes massive overcounting. The API headers are the only reliable source.

---

Auto-start

Windows

1. Win + R → shell:startup
2. Create a shortcut to start_widget.bat in that folder

macOS

Add to Login Items in System Settings → General → Login Items, or create a Launch Agent.

---

Troubleshooting

Shows "connecting…" → Make sure Claude Code is installed and you have run claude at least once.

Shows "API err" → Token may have expired. Run claude in a terminal to refresh.

No tray icon on macOS → Install/upgrade pystray: pip install --upgrade pystray

Widget is behind other windows → Right-click → Pin.

---

Contributing

Pull requests welcome. Please open an issue first to discuss major changes.

License

MIT — free to use, modify, and distribute. No warranty.