winget install --id=SlavomirDurej.claude-usage-widget -e A beautiful, standalone desktop widget for Windows, macOS, and Linux that displays your Claude.ai usage statistics in real-time.
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:
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.
> 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.
Windows:
Claude-Usage-Widget-{version}-win-Setup.exe (installer) or Claude-Usage-Widget-{version}-win-portable.exe (no install needed) from ReleasesWin+R, type shell:startup, and copy the portable .exe into that folder. To update, copy the new version in and delete the old one.macOS:
Claude-Usage-Widget-{version}-macOS-arm64.dmg (Apple Silicon) or Claude-Usage-Widget-{version}-macOS-x64.dmg (Intel) from Releases> ⚠️ 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.app >
> Then try launching the app again.
Linux:
Claude-Usage-Widget-{version}-linux-x86_64.AppImage (Intel/AMD) or Claude-Usage-Widget-{version}-linux-arm64.AppImage (ARM) from Releaseschmod +x Claude-Usage-Widget-*.AppImage./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:
> bash > 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.AppImage
2. 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
EOF
> Note: The --no-sandbox flag 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:
git clone https://github.com/SlavomirDurej/claude-usage-widget.git
cd claude-usage-widget
npm install
npm start
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:
"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 install
If issues persist, open a Support discussion with your OS, Node.js version, and full error output.
Special thanks to these contributors who have improved the widget:
This project is licensed under the MIT License - see the LICENSE file for details.
Built with Electron · Releases · Discussions