Claude Usage Widget

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:

    terminalhtop vibe, green-on-black
    dashboardBloomberg-terminal cool blue
    hudcar-dashboard amber

    receipt (light)thermal-paper cream + red
    stripcool mint on mono-gray
    brutalist (light)white, heavy rules, crimson

Gauge variants for every theme are available at screenshots/osd-gauge-.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…