Show HN: Desktop OSD that reads Claude Code's rate limit headers

A cross-platform desktop widget that displays your Claude Code usage limits in real time. Always-on-top OSD overlay showing session and weekly utilization — built with PySide6 (Qt), so a single pip install works on Linux, macOS, and Windows. Always-on-top OSD: session + weekly utilisation, reset timers, and the ● LIVE token-per-minute badge while a Claude Code session is writing. Click the OSD to open the detail popup: forecasts, 5h/7d sparklines, 90-day heatmap, 52-week GitHub-style calendar, per-model cost breakdown with Anthropic-published rates, top projects, tips, and a Claude-authored weekly summary. - Single pip install -- noapt /brew /system libraries required, Qt is bundled - Real API data -- rate-limit utilisation read straight from anthropic-ratelimit-unified-* response headers - OSD overlay -- transparent, frameless, always-on-top; left-click opens the details popup, right-click shows a context menu - Live token stream -- ● LIVE 5.3k tok/min badge on the OSD while a Claude Code session is actively writing, derived from the conversation JSONLs - Detail popup -- usage bars, forecast, 5h/7d sparklines, 90-day heatmap, 52-week GitHub-style calendar, per-model cost breakdown, top projects, active sessions (resizable) - Auto-refresh -- every 30 seconds by default, fully configurable - Resizable -- scroll wheel on the OSD (0.6x -- 2.0x); drag the popup window edges to widen it - Draggable -- left-click drag on the OSD - Cost estimation -- USD equivalent per model, cache savings, pay-as-you-go comparison for flat-fee subscribers - Usage forecasting -- burn-rate prediction: "At current rate: 2h 30m to limit" - Per-project breakdown -- top 5 projects by token usage today - Prompt-cache opportunities -- scans recent sessions for repeated prompt prefixes and suggests cache_control changes with a concrete $ savings estimate - AI-generated weekly report -- Claude Haiku writes a 3-4 sentence summary of your past week of usage (cached 1h; never leaks prompt text) - Anomaly detection -- flags days whose utilisation exceeds the 7/90-day baseline - Cost optimisation tips -- suggests cache-hit-rate improvements and model-mix changes - Themes -- default, catppuccin-mocha, dracula, nord, gruvbox-dark - Threshold notifications -- native desktop notifications on crossing 75% / 90% - Webhooks -- optional POST to Slack / Discord / custom URLs on threshold, daily, or anomaly events - Localhost JSON API -- optional http://127.0.0.1:8765/usage for tmux / polybar / waybar integrations (prompt previews redacted at the serialization boundary) - CLI mode -- --json ,--field ,--export csv for scripts and status bars - Python 3.10+ - Claude Code CLI installed and authenticated (OAuth) — the widget reads the same token from ~/.claude/.credentials.json (or macOS Keychain) pip install --user --upgrade claude-usage-widget claude-usage # launches the OSD overlay claude-usage --version # 0.4.1 That's it — no apt , no brew , no PyGObject, no rumps. PySide6 ships Qt in the wheel, so the widget is fully self-contained. If you prefer brew over pip : brew tap bozdemir/tap brew install claude-usage-widget git clone https://github.com/bozdemir/claude-usage-widget.git cd claude-usage-widget pip install -e . python3 main.py | Action | Effect | |---|---| | Left-click | Open the details popup | | Left-click drag | Move the OSD | | Right-click | Open context menu (Details, Refresh, Opacity, Minimize, Quit) | | Scroll up / down | Resize (0.6x -- 2.0x) | - Details… -- open the detail popup - Refresh -- force an immediate data refresh - OSD Opacity -- 100% / 75% / 50% / 25% - Minimize / Restore -- collapse the OSD to a thin progress strip - Quit -- exit the widget All settings are optional. Copy config.json.example to config.json and edit the values you want to change: cp config.json.example config.json { "daily_message_limit": 200, "weekly_message_limit": 1000, "daily_token_limit": 5000000, "weekly_token_limit": 25000000, "refresh_seconds": 30, "osd_opacity": 0.75, "osd_scale": 1.0 } | Setting | Default | Description | |---|---|---| refresh_seconds | 30 | How often to fetch new data from the API (seconds) | osd_opacity | 0.75 | OSD background opacity (0.15--1.0) | osd_scale | 1.0 | OSD scale factor (0.6--2.0) | daily_message_limit | 200 | Daily message limit for local tracking in the popup | weekly_message_limit | 1000 | Weekly message limit for local tracking in the popup | daily_token_limit | 5000000 | Daily token limit for local tracking | weekly_token_limit | 25000000 | Weekly token limit for local tracking | claude_dir | ~/.claude | Path to the Claude Code data directory | theme | default | Color theme for the OSD and popup. One of default , catppuccin-mocha , dracula , nord , gruvbox-dark | Keys omitted from config.json fall back to built-in defaults. claude_dir is not included in the example file because the default is correct for most setups. The widget ships with 5 built-in color themes. Select one by adding "theme": "" to your config.json : { "theme": "dracula" } Available themes: - default -- the original widget palette (screenshots welcome) - catppuccin-mocha -- soft pastel dark theme (screenshots welcome) - dracula -- classic purple-and-pink dark theme (screenshots welcome) - nord -- cool arctic blue palette (screenshots welcome) - gruvbox-dark -- warm retro-style dark theme (screenshots welcome) The widget reads your Claude Code OAuth credentials from ~/.claude/.credentials.json (Linux) or the macOS Keychain and makes a minimal API call (max_tokens=1 to claude-haiku-4-5-20251001 ) to read the rate-limit response headers: anthropic-ratelimit-unified-5h-utilization: 0.58 anthropic-ratelimit-unified-5h-reset: 1776186000 anthropic-ratelimit-unified-7d-utilization: 0.10 anthropic-ratelimit-unified-7d-reset: 1776690000 These are the same values shown on the claude.ai usage page. The widget also reads local data from ~/.claude/ for message counts, token usage per model, and active session tracking. Qt's QWidget with FramelessWindowHint | Tool | WindowStaysOnTopHint plus WA_TranslucentBackground gives us a transparent, borderless floating window that behaves identically on X11, XWayland, native Wayland, macOS, and Windows. All drawing goes through QPainter (drawRoundedRect , drawText ), so there's a single code path with no platform shims. Scale and opacity -- the overlay stores a scale (0.6 -- 2.0, default 1.0) and opacity (0.15 -- 1.0, default 0.75). Scale multiplies every pixel dimension before drawing, so the widget resizes proportionally. Opacity is the alpha channel of the background fill only; bar and text remain at full alpha so they stay legible at low opacity. Refresh cycle -- a daemon thread wakes every refresh_seconds (default 30), performs the API call, and emits a Qt signal back to the GUI thread (Signal(object) ). The GUI thread then updates the OSD and the popup together. User interactions (scroll, drag, right-click) update in place and request an immediate repaint. The OSD renders a ● LIVE ~5.3k tok/min badge when a Claude Code session is actively writing. The detector scans ~/.claude/projects/*/*.jsonl for assistant turns in the last 5 minutes (filtered cheaply by file mtime), sums their output_tokens , and divides by the window. The "live" dot only lights up when the newest turn is under 90 seconds old; the rate keeps showing for the full 5-minute window so bursts are visible in context. Scans your recent conversation history for repeated user-prompt prefixes (≥1024 tokens, ≥3 occurrences within the last 7 days) and estimates how much you'd save by enabling Anthropic's ephemeral prompt cache on them (cache_creation write once + cache_read for the rest). The top 5 are shown in the popup with a $ figure. Prompt previews stay local -- they're redacted from --json and the localhost API so raw prompt text never leaves your machine via those surfaces. A 3-4 sentence natural-language summary of the past week (top projects, total volume, cost/model mix) is generated on demand by Claude Haiku 4.5 and cached at ~/.claude/widget-cache/weekly-report.json for one hour. The generator runs on a background thread so refresh stays synchronous. If the OAuth token is missing or Anthropic is unreachable, the section simply disappears -- no retries, no errors in your face. GitHub-style yearly activity grid below the 90-day strip. Rows are weekdays (Sunday at the top), columns are ISO weeks with today anchored in the rightmost column at its real weekday. Cell alpha maps to per-day peak session utilisation. - Check if the process is running: ps aux | grep claude-usage (Linux/macOS) or the Task Manager (Windows). - Try launching from a terminal: claude-usage — any startup error prints to stderr. Qt 6.5+ needs one tiny system library that ships separately from the wheel: sudo apt install -y libxcb-cursor0 # Ubuntu/Debian sudo dnf install -y xcb-util-cursor # Fedora sudo pacman -S xcb-util-cursor # Arch The widget shoots notifications via notify-send . Install it if missing: sudo apt install libnotify-bin # Ubuntu/Debian sudo dnf install libnotify # Fedora sudo pacman -S libnotify # Arch - Make sure the Claude Code CLI is installed and you are logged in (the claude command should work in a terminal). - Linux / Windows: the OAuth token is read from ~/.claude/.credentials.json . - macOS: the OAuth token is read from the Keychain, with a fallback to ~/.claude/.credentials.json . Contributions are welcome. A few guidelines: - Bug reports — open an issue with your OS, Python version, and the full error output. - Pull requests — keep changes focused. One fix or feature per PR. Run the widget manually before submitting. - No new runtime dependencies — PySide6-Essentials is the only runtime dep. Everything else uses the Python stdlib and platform-native CLIs. - Code style — follow the existing conventions. No formatter is enforced; just match the surrounding code. MIT