A developer going by bozdemir just dropped claude-usage-widget on GitHub โ a cross-platform desktop OSD that reads your Claude Code usage directly from the anthropic-ratelimit-unified-* response headers. Think of it as a always-on-top HUD for your API consumption, built with PySide6 so a single pip install works on Linux, macOS, and Windows without hunting down system libraries.
Real-Time Usage Overlay
The widget displays session and weekly utilization in a transparent, frameless floating window. It auto-refreshes every 30 seconds (configurable) and pulls the same rate-limit data you'd see on claude.ai. The OSD shows a live token-per-minute badge when Claude Code is actively writing โ it scans your local JSONL conversation files to calculate the throughput on the fly.
Per-Turn Cost Ticker
The scrolling cost strip along the bottom is where things get interesting. Each assistant turn shows its USD cost color-coded by quartile (dim โ blue โ amber โ red), so you can see at a glance whether you're burning through budget or running lean. The widget pulls pricing data from Anthropic's published rates and handles multi-tool turns with compact labels like "Read+2". Toggle it via right-click or config.
Deep Usage Analytics
Click the OSD and you get a full detail popup: 5h/7d sparklines, 90-day heatmap, 52-week GitHub-style calendar, per-model cost breakdown with Anthropic rates, top projects by token usage, and even an AI-generated weekly summary written by Claude Haiku. It also scans for prompt-cache opportunities โ repeated prefixes that could benefit from Anthropic's ephemeral cache, complete with dollar savings estimates.
Subagent Detection
When you spawn parallel subagents via the Task tool, a โ N badge appears next to the CLAUDE title showing how many are currently writing. The detection is stat-only (mtime filtering on subagent JSONLs) so it's essentially free โ hidden when the count is zero to keep single-session use clean.
Themes and Integrations
Five built-in themes ship standard: default, catppuccin-mocha, dracula, nord, and gruvbox-dark. The widget also exposes a localhost JSON API at port 8765 for tmux, polybar, or waybar integration. CLI mode supports --json, --field, and --export csv for scripts.
Installation
Version 0.4.3 is live on PyPI. Requirements: Python 3.10+ and Claude Code CLI authenticated with OAuth (reads tokens from ~/.claude/.credentials.json or macOS Keychain). One command: pip install --user claude-usage-widget && claude-usage. That's it โ no apt, no brew, no manual Qt hunting.
Key Takeaways
- Reads rate-limit headers directly from Anthropic API (anthropic-ratelimit-unified-5h/7d-utilization)
- Live token-per-minute badge derived from local JSONL conversation files
- Per-turn cost ticker with quartile color-coding for budget visibility
- Subagent counter badge shows parallel Task tool usage in real-time
- 52-week GitHub-style calendar heatmap tracks daily utilization patterns
- Five themes, CLI mode, localhost API for status bar integrations
The Bottom Line
This is exactly the kind of tool the Claude Code ecosystem needed โ transparent visibility into what you're burning before you hit the limit mid-sprint. The cost ticker alone is worth the install for anyone on a flat-fee plan trying to optimize their model mix. Bonus points for the subagent counter; now you can finally see how many parallel workers you're actually spawning without digging through logs.