A beautiful, standalone desktop widget for Windows, macOS, and Linux that displays your Claude.ai usage statistics in real-time.
🎯 Real-time Usage Tracking — Monitor both session and weekly usage limits
📊 Visual Progress Bars — Clean, gradient progress indicators with configurable warning thresholds
⏱️ Countdown Timers — Circular timers showing time elapsed in the current session window
🔄 Auto-refresh — Updates every 5 minutes automatically, with animated refresh indicator
📈 Usage History Graph — Toggleable 7-day chart showing session and weekly trends over time
🌍 Currency Support — Extra usage displays your account's billing currency (€, £, $)
🎨 Modern UI — Sleek, draggable widget with dark and light themes
🔒 Secure — Encrypted credential storage
📍 Always on Top — User-controlled, stays visible across all workspaces
💾 System Tray — Minimizes to tray for easy access
⚙️ Settings Panel — Persistent preferences for startup, theme, tray, thresholds, and date/time formats
🔔 Usage Alerts — Desktop notifications when usage crosses configurable warn/danger thresholds
🔔 Update Notifications — Automatic check for new releases on startup
🕐 Configurable Date & Time Formats — 12h/24h time, and flexible weekly reset date display
📐 Compact Mode — Minimal view for when you just need a quick glance
All usage bars (Session, Weekly, and Extra Usage) now respect your configured warning and danger thresholds:
- Green below warning threshold
- Amber at or above warning threshold
- Red at or above danger threshold
Changes apply immediately when thresholds are adjusted in Settings.
A toggleable usage history graph now sits below the main widget. Click the graph button in the toolbar to show or hide it.
- Displays up to 7 days of collected usage data points
- Data points are captured each time the app refreshes (every 5 minutes by default when running)
- History persists across restarts — collected data is retained when you close and reopen the app
- Sonnet and Extra Usage lines appear automatically when those sections are relevant
- Adaptive x-axis labels — shows times for short spans, weekday+hour for medium spans, and dates for longer spans
- Respects your 12h/24h time format setting
- Hover tooltip shows exact timestamp and value
Note: The graph shows usage snapshots captured at each refresh interval while the app is running. Time periods when the app is closed are not represented on the graph.
The Extra Usage row now displays the correct currency symbol based on your account's billing currency — €, £, or $.
For full release history, see the Releases page.
- ⚙️ Launch at startup — Auto-start with Windows or macOS login
- 📌 Hide from taskbar — Tray-only mode
- 🎨 Theme selector — Dark / Light / System
⚠️ Warning thresholds — Configurable amber and red levels for usage bars- 🔔 Usage alerts — Desktop notifications at warn/danger thresholds
- 🕐 Time format — 12h or 24h
- 📅 Date format — Controls how the weekly reset date is displayed
- 📐 Compact mode — Minimal two-bar view
Windows:
- Download the latest
Claude-Usage-Widget-{version}-win-Setup.exe(installer) orClaude-Usage-Widget-{version}-win-portable.exe(no install needed) from Releases - Run the installer or portable exe
- Launch "Claude Usage Widget" from the Start Menu (installer) or directly (portable)
macOS:
- Download the latest
Claude-Usage-Widget-{version}-macOS-arm64.dmg(Apple Silicon) orClaude-Usage-Widget-{version}-macOS-x64.dmg(Intel) from Releases - Open the DMG and drag the app to your Applications folder
- Launch "Claude Usage Widget" from Applications
⚠️ macOS Security Notice: Because this app is not yet notarized with Apple, macOS Gatekeeper may show a "damaged or can't be opened" warning. To fix this, run the following command in Terminal after installing:xattr -cr /Applications/Claude\ Usage\ Widget.appThen try launching the app again.
Linux:
- Download the latest
Claude-Usage-Widget-{version}-linux-x86_64.AppImage(Intel/AMD) orClaude-Usage-Widget-{version}-linux-arm64.AppImage(ARM) from Releases - Make it executable:
chmod +x Claude-Usage-Widget-*.AppImage - Run it:
./Claude-Usage-Widget-*.AppImage
Note: AppImage runs without installation on most Linux distributions. On Ubuntu 22.04+, you may need to install a dependency first:
sudo apt install libfuse2
By default the AppImage runs from wherever you put it. To get a clickable icon in your app launcher (and optionally launch at login), follow these steps.
1. Place the AppImage somewhere permanent:
mkdir -p ~/.local/bin
mv Claude-Usage-Widget-*.AppImage ~/.local/bin/claude-usage-widget.AppImage
chmod +x ~/.local/bin/claude-usage-widget.AppImage2. Create a desktop entry:
cat > ~/.local/share/applications/claude-usage-widget.desktop << EOF
[Desktop Entry]
Name=Claude Usage Widget
Comment=Monitor Claude.ai usage
Exec=$HOME/.local/bin/claude-usage-widget.AppImage --no-sandbox
Icon=$HOME/.local/bin/claude-usage-widget.AppImage
Terminal=false
Type=Application
Categories=Utility;
StartupNotify=true
EOFNote: The
--no-sandboxflag is required for Electron-based AppImages on most Linux systems due to sandbox namespace restrictions. This is an Electron/Chrome limitation, not specific to this widget.
3. Register the entry:
update-desktop-database ~/.local/share/applications/The widget should now appear in your application launcher. Test it by launching from your app menu before proceeding to autostart.
4. Autostart at login (optional):
mkdir -p ~/.config/autostart
cp ~/.local/share/applications/claude-usage-widget.desktop ~/.config/autostart/Prerequisites:
- Node.js 18+ (Download)
- npm (comes with Node.js)
git clone https://github.com/SlavomirDurej/claude-usage-widget.git
cd claude-usage-widget
npm install
npm start- Launch the widget
- Click "Login to Claude" when prompted
- A browser window will open — log in to your Claude.ai account
- The widget will automatically capture your session
- Usage data will start displaying immediately
- Drag — Click and drag the title bar to move the widget
- Refresh — Click the refresh icon to update data immediately
- Graph — Click the graph icon to toggle usage history
- Minimize — Click the minus icon to hide to system tray / dock
- Close — Click the X to Close the app
Right-click the tray icon for: Show/Hide, Refresh, Re-login, Settings, Exit.
| Column | Description |
|---|---|
| Session Used | Progress bar showing usage from 0–100% |
| Elapsed | Circular timer showing how far through the window you are |
| Resets In | Countdown until the window resets |
| Resets At | Actual local clock time / date when the window resets |
Color Coding:
- 🟣 Purple: Normal usage (below warning threshold, default 75%)
- 🟠 Orange: High usage (above warning threshold)
- 🔴 Red: Critical usage (above danger threshold, default 90%)
- Credentials stored locally only using encrypted storage
- No data sent to any third-party servers
- Only communicates with the official Claude.ai API
- Logout clears all session data, cookies, and Electron session storage
"Login Required" keeps appearing — Session may have expired. Click "Login to Claude" to re-authenticate.
Widget not updating — Check internet connection, click refresh manually, or try re-logging in from the tray menu.
Build errors — Clean reinstall resolves most issues:
rm -rf node_modules package-lock.json
npm installIf issues persist, open a Support discussion with your OS, Node.js version, and full error output.
- macOS support
- Linux support
- Settings panel
- Remember window position
- Custom warning thresholds
- Configurable date & time formats
- Update notifications
- Usage alerts at thresholds
- Compact mode
- Usage history graph
- Currency support
- Organization/Teams support
- Keyboard shortcuts
Special thanks to these contributors who have improved the widget:
- @cwil2072 - macOS minimize/restore fix, usage history graph
- @dion-jy - Login flow architecture improvements
- @goooseman - Login window security improvements
- @sergkuzn - Linux desktop launcher & autostart documentation
This project is licensed under the MIT License - see the LICENSE file for details.
Built with Electron · Releases · Discussions