How niccolo-sabato/claude-usage-widget works
Claude Usage Widget is a Windows desktop monitor for Claude.ai session, weekly, and model-specific limits; its central workflow is fetching account usage and presenting compact taskbar bars with reset information. The widget also supports saved accounts and Claude Code login switching. A companion browser extension retrieves and copies the Claude session key for setup. Widget internals are represented at the available source-path level because its implementation was not excerpted; README-documented capabilities are retained, while uncertain internal call paths are omitted.
Main entry points: widget.pyw Usage widget · popup.js Key popup · cookieService.js Cookie service · background.js Background worker
Components 16
Desktop widget
- Usage widget
src/widget.pyw - Usage refresh
src/widget.pyw - Usage bars
src/widget.pyw - Display preferences
src/widget.pyw - Threshold alerts
src/widget.pyw
Account management
- Account switching
src/widget.pyw - Claude Code CLI
src/cc_cli.py - OAuth profiles
src/cc_accounts.py
Browser extension
- Key popup
extension/popup.js - Cookie service
extension/lib/cookieService.js - Background worker
extension/background.js
Platform integration
- Taskbar behavior
src/widget.pyw
Other components
- User
- Claude.ai
- Windows
- Browser
Connections 19
- User → Usage widget: views and configures
README.md - Usage widget → Usage refresh: requests refresh
README.md - Usage refresh → Claude.ai: fetches usage
README.md - Usage refresh → Usage bars: updates bars
README.md - Usage widget → Display preferences: configures display
README.md - Usage refresh → Threshold alerts: triggers thresholds
README.md - Usage widget → Taskbar behavior: positions widget
README.md - User → Account switching: switches account
README.md - Account switching → Claude Code CLI: switches Claude Code login
README.md - Claude Code CLI → OAuth profiles: uses profile operations
src/cc_cli.py - OAuth profiles → Claude.ai: renews OAuth login
- User → Key popup: opens popup
extension/popup.js - Key popup → Cookie service: gets session key
extension/popup.js - Cookie service → Browser: reads cookie
extension/lib/cookieService.js - Browser → Claude.ai: holds session
- Background worker → Cookie service: checks session
extension/background.js - Background worker → Browser: sets badge and surface
extension/background.js - Key popup → Usage widget: provides setup key
README.md - Usage widget → Windows: uses taskbar integration
README.md