Claude Usage Widget

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.

Screenshots

Always-on-top OSD: session + weekly utilisation, reset timers, live token-per-minute badge, subagent counter, and a scrolling per-turn cost ticker along the bottom.

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.

OSD view modes

Two layouts, switch with right-click → OSD View ▸. Selection persists to ~/.config/claude-usage/config.json so a restart keeps it.

Bars — default, includes the scrolling ticker	Gauge — circular rings, car-dashboard vibe

Themes

11 built-in palettes — 5 classics + 6 Claude-designed skins. Right-click the OSD → Theme ▸ to switch instantly; the choice persists to ~/.config/claude-usage/config.json.

Classics (dark):

default	catppuccin-mocha	dracula
nord	gruvbox-dark

Claude-designed skins:

terminal htop vibe, green-on-black	dashboard Bloomberg-terminal cool blue	hud car-dashboard amber
receipt (light) thermal-paper cream + red	strip cool mint on mono-gray	brutalist (light) white, heavy rules, crimson

Gauge variants for every theme are available at screenshots/osd-gauge-<theme>.png.

Features

• Single pip install -- no apt/brew/system libraries required, Qt is bundled
• Real API data -- 5h / 7d plan utilisation read from Claude Code's /api/oauth/usage endpoint (the same data the Claude UI shows)
• Model-scoped weekly bar -- when Anthropic reports a separate weekly cap for a specific model (e.g. Fable), a third bar appears automatically below Session and Weekly, labelled with the model name. It auto-hides when the API stops reporting it — works in bars, gauge, all 11 themes, and the detail popup.
• Second provider (opt-in) -- also track your local OpenAI Codex usage alongside Claude's: add "codex" to the providers config and the widget shows Codex 5h/weekly rows beneath Claude's (extra bars in bars view, a 2×2 ring grid in gauge), rendered natively in all 11 themes. Auto-hides when the Codex CLI is missing or logged out; off by default. See Second provider: OpenAI Codex.
• OSD overlay -- transparent, frameless; left-click opens the details popup, right-click shows a context menu. Stays on top by default — toggle it off to use it as a background desktop widget.
• 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
• Per-turn cost ticker -- a scrolling strip at the bottom of the OSD shows the USD cost of each assistant turn as it lands ($0.156 ← Bash · 116), colour-coded by quartile within the visible window so the tape always stays visually varied. Toggle via right-click → "Show cost ticker" or set "show_ticker": false in config.json.
• Live news ticker (opt-in) -- a second scrolling strip shows the latest Anthropic/Claude headlines sourced from Hacker News (top stories with 50+ upvotes). Fetched lazily, cached locally for 1 hour. Click the strip to open the article in your browser. Off by default because it makes outbound calls to a 3rd-party feed; enable via right-click → "Show news ticker" or set "show_news": true in config.json.
• Subagent badge -- when you spawn parallel subagents via the Task tool, the CLAUDE title gets a ⚙ N counter next to it showing how many are currently writing. Hidden when zero so single-session use isn't cluttered.
• 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 60 seconds by default; the interval adapts automatically, backing off up to 300 s when the endpoint rate-limits and snapping back on the next clean refresh (refresh_seconds / refresh_max_seconds)
• Positioning -- snap the OSD to any screen corner via right-click → "OSD Position", or drag it anywhere; the spot is remembered (osd_position, osd_x/osd_y)
• Resizable -- scroll wheel on the OSD (0.6x -- 4.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
• Real-time burn/spike alerts -- a bright OSD badge (▲42% / ▲SPIKE / ▲STORM) plus a debounced, once-per-episode notification when your 5-hour window burns abnormally fast or a single turn / retry-loop spikes tokens. The badge renders on the 5 classic themes for now; notifications and the burn_alert webhook fire on all 11
• Peak-window awareness -- an unobtrusive popup hint during Anthropic's weekday reduced-limit window (default ~5–11 AM Pacific; fully configurable)
• Monthly budget -- optional spend cap: set monthly_budget_usd to see month-to-date + projected end-of-month spend in the popup and get a once-per-month heads-up when you're on track to exceed it
• Themes -- 11 in all: 5 classic palettes (default, catppuccin-mocha, dracula, nord, gruvbox-dark) plus 6 designed skins (terminal, dashboard, hud, receipt, strip, brutalist)
• Threshold notifications -- native desktop notifications on crossing 75% / 90%
• Webhooks -- optional POST to Slack / Discord / custom URLs on threshold, daily-report, anomaly, budget-projection, or burn-alert 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, --once, --field, --export csv|json (with --days N, default 30) for scripts and status bars, plus --statusline for Claude Code's built-in statusLine
• Update notifications -- a daily background check against the GitHub Releases API; when a newer version is published you get one desktop notification and a banner in the right-click menu (notified once per version, never nagging). The running build's version is also shown at the foot of the menu.
• Single-instance guard -- a second claude-usage launch (login item, script, double-click) detects the running one via a per-user lock file and exits cleanly instead of stacking a duplicate OSD; a lock left behind by a crashed instance is reclaimed automatically.

Requirements

• Python 3.10+
• Claude Code CLI installed and authenticated (OAuth) — the widget reads the same token, checking the CLAUDE_CODE_OAUTH_TOKEN environment variable first, then ~/.claude/.credentials.json, then the macOS Keychain

Installation

Any platform (pip — recommended)

pip install --user --upgrade claude-usage-widget
claude-usage              # launches the OSD overlay (foreground)
claude-usage --detach     # …or run it in the background and free the shell (Linux/macOS; on Windows use Start-Process or pythonw)
claude-usage --version    # 0.12.5

That's it — no apt, no brew, no PyGObject, no rumps. pip pulls in just two pure-Python wheels (PySide6-Essentials, which ships Qt, and certifi for HTTPS), so the widget is self-contained with zero system libraries.

# ~/.config/systemd/user/claude-usage.service
[Unit]
Description=Claude Usage Widget
After=graphical-session.target

[Service]
ExecStart=%h/.local/bin/claude-usage
Restart=on-failure

[Install]
WantedBy=graphical-session.target

systemctl --user enable --now claude-usage

macOS (Homebrew — optional)

If you prefer brew over pip:

brew tap bozdemir/tap
brew install claude-usage-widget

From source

git clone https://github.com/bozdemir/claude-usage-widget.git
cd claude-usage-widget
pip install -e .
python3 main.py

Usage

OSD overlay controls

Context menu (right-click OSD)

• (usage summary) -- a dim, non-clickable header at the top showing your live session/weekly % (with the live token-per-minute rate while a session is writing)
• Details… -- open the detail popup
• Refresh -- force an immediate data refresh
• OSD Opacity -- 100% / 75% / 50% / 25%
• OSD View ▸ -- switch between Bars (default — progress bars + cost ticker) and Gauge (two circular rings); auto-persisted
• OSD Position ▸ -- snap the overlay to Top Left / Top Right / Bottom Left / Bottom Right, or drag it anywhere for a remembered Custom position; auto-persisted
• Theme ▸ -- pick one of the 11 themes (5 classic palettes plus 6 skins: terminal, dashboard, hud, receipt, strip, brutalist); the choice persists to ~/.config/claude-usage/config.json so a restart keeps it
• Minimize / Restore -- collapse the OSD to a thin progress strip
• Show cost ticker -- toggle the scrolling per-turn cost strip on the OSD
• Show news ticker -- toggle the Anthropic/Claude news headline strip on the OSD
• Always on top -- keep the OSD pinned above other windows (default), or turn it off to let it sit as a normal background desktop widget the window manager stacks behind your focused windows; persisted
• claude-usage v<version> -- a dim, disabled line showing the running build's version; when a newer release is published an ↑ Update available: <tag> banner appears at the top of the menu, under the usage summary (click to copy the pip install --upgrade command)
• Updated <time> ago -- a dim, non-clickable line showing how long since the last successful refresh
• Quit -- exit the widget

Statusline-fed rate limits

If your Claude Code statusLine command dumps its rate-limit payload to a JSON file, the widget can use it as a zero-cost data source — Claude Code rewrites the statusline continuously during an active session, so the file carries the same numbers as /api/oauth/usage at seconds freshness and no API spend. Point statusline_cache_path at a file shaped like:

{
  "captured_at": "2026-07-11T22:52:05+09:00",
  "rate_limits": {
    "five_hour": {"used_percentage": 54, "resets_at": 1783795800},
    "seven_day": {"used_percentage": 46, "resets_at": 1784026800}
  }
}

With this configured the widget uses it two ways:

• Endpoint relief — while the dump is younger than 2 × refresh_seconds, the /api/oauth/usage call is skipped and only forced through at most once per usage_endpoint_min_seconds. The endpoint is a low-budget resource shared with Claude Code itself; the forced calls keep the model-scoped/overage fields fresh and pick up consumption from headless claude -p runs, which never render a statusline.
• Rate-limit fallback — when the endpoint throttles us, a dump younger than 20 minutes beats the last on-disk sample, which can lag a whole rate-limit window behind.

Producing the file is up to your statusline script (it receives the payload from Claude Code on stdin and can tee the relevant part out). Expired windows in a stale dump are clamped to zero, and a missing/garbled file just disables the feature for that refresh.

Second provider: OpenAI Codex (opt-in)

Run OpenAI Codex alongside Claude Code? The widget can show its usage too, right beneath Claude's — no separate menu-bar app. Add "codex" to providers in config.json:

{
    "providers": ["claude", "codex"]
}

You get two extra rows in bars view — Codex 5h and Codex 7d — or a second pair of rings (a 2×2 grid) in gauge view, styled to match whichever of the 11 themes you're on.

• Data source — the widget speaks JSON-RPC over stdio to your local codex app-server (account/rateLimits/read) — the same numbers codex reports itself. No scraping, no account data stored or logged.
• Cheap — the RPC is spawned at most once per codex_poll_seconds (default 300 s), with an on-disk cache served in between; the read is hard-bounded so a stalled codex can never hang a refresh.
• Graceful — the Codex rows auto-hide when the codex CLI is missing, logged out, or returns no rate-limit data. POSIX-only for now (Linux/macOS).

The default providers is ["claude"], so existing users see no change.

Configuration

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": 60,
    "refresh_max_seconds": 300,
    "osd_opacity": 0.75,
    "osd_scale": 1.0
}

Keys omitted from config.json fall back to built-in defaults, so config.json.example is an intentionally minimal starter listing only the most commonly changed keys. Everything else in the table above — the opt-in providers (Codex), statusline/endpoint tuning, the burn / peak / budget alerts, the localhost API, webhooks, and the auto-persisted OSD state — simply uses its default until you add it.

Themes

The widget ships with 11 built-in color themes — 5 classics plus 6 Claude-designed skins. Select one by adding "theme": "<name>" to your config.json:

{
    "theme": "dracula"
}

Available themes (gallery above):

Classics (dark):

• default -- the original widget palette
• catppuccin-mocha -- soft pastel dark theme
• dracula -- classic purple-and-pink dark theme
• nord -- cool arctic blue palette
• **gruvbox-d