Home

Claude Usage Widget

A cross-platform desktop widget that shows your Claude Code usage limits in real time — an always-on-top OSD overlay with session & weekly utilization, reset timers, a live tokens-per-minute badge, and a scrolling per-turn cost ticker. Built with PySide6 (Qt), so a single pip install works on Linux, macOS, and Windows.

pip install --user --upgrade claude-usage-widget
claude-usage --detach     # run in the background, frees your shell

---

Wiki contents

Page	What's in it
Installation	pip, Homebrew, from-source; requirements; --detach
Usage	OSD controls, the right-click menu, CLI flags
Configuration	every config.json key, with defaults
Themes	the 11 built-in palettes + gallery
Shell Integrations	tmux, waybar, polybar, starship, zsh, localhost API
How It Works	architecture: OSD, refresh loop, pricing, caching
Troubleshooting	xcb plugin, notifications, auth, blank values
FAQ	common questions
Contributing	PR/issue guidelines, dev setup

---

What it does at a glance

• Real API data — plan utilization straight from Anthropic's /api/oauth/usage endpoint (the same numbers as the claude.ai usage page).
• OSD overlay — transparent, frameless, always-on-top. Left-click opens a detail popup, right-click opens a menu, scroll resizes, drag moves.
• Two view modes — Bars (with cost ticker) and Gauge (circular rings).
• 11 themes — 5 dark classics + 6 Claude-designed skins, switchable at runtime.
• Detail popup — forecasts, 5h/7d sparklines, 90-day heatmap, 52-week calendar, per-model cost breakdown, top projects, active sessions, and an AI-written weekly summary.
• Power-user surfaces — CLI (--json / --field / --export), a localhost JSON API, webhooks, and desktop threshold notifications.

See Usage for the full feature tour.

---

Requirements

• Python 3.10+
• Claude Code CLI installed and authenticated (OAuth) — the widget reuses the token in ~/.claude/.credentials.json (or the macOS Keychain). It never asks for credentials of its own.

---

Links

• 📦 PyPI
• 🍺 Homebrew: brew tap bozdemir/tap && brew install claude-usage-widget
• 🐛 Issues
• 📄 License: MIT