Claude-Usage-Widget is a desktop widget designed to display real-time usage statistics for Claude.ai on Windows, macOS, and Linux. This tool provides users with an at-a-glance view of their Claude.ai session and weekly limits, helping them stay informed and manage their usage efficiently.
Key Features:
Real-time Usage Tracking: Monitor both session and weekly limits in real-time.
Circular Countdown Timers: Track time elapsed in the current session window.
Auto-refresh: Updates every 5 minutes automatically with an animated refresh indicator.
Usage History Graph: Toggleable 7-day chart showing trends over time.
Currency Support: Displays usage in your account's billing currency (€, £, $).
Modern UI Design: Sleek, draggable widget with dark and light themes.
Secure Credential Storage: Encrypted for added security.
System Tray Functionality: Minimizes to tray for easy access.
Persistent Settings Panel: Customizable preferences for startup, theme, tray, thresholds, and more.
Target Audience and Benefits:
Ideal for Claude.ai users seeking real-time insights into their usage without switching tabs or logging in multiple times. The widget helps prevent overages by providing clear visual indicators of session and weekly limits, while its compact design ensures it stays out of your way yet always visible when needed. Available via Winget, install Claude-Usage-Widget on Windows with ease using the winget command line.
README
Claude Usage Widget
A beautiful, standalone desktop widget for Windows, macOS, and Linux that displays your Claude.ai usage statistics in real-time.
Features
🎯 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
🧩 Per-Model Breakdowns — Rows and chart lines for Sonnet, Opus, Fable, Cowork, OAuth Apps, and Design usage when your account reports them
💳 Credit Clarity — Monthly spend cap and credit balance shown separately, with a promo-vs-purchased split and expiry warnings
👥 Multi-Account Support — Run isolated instances for separate accounts via the --profile flag (see below)
> For a full history of changes by version, see Release Notes.
⚙️ 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 view
Installation
Download Pre-built Release
Windows:
Download the latest Claude-Usage-Widget-{version}-win-Setup.exe (installer) or Claude-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)
To launch at Windows startup (portable only): Press Win+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:
Download the latest Claude-Usage-Widget-{version}-macOS-arm64.dmg (Apple Silicon) or Claude-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.app >
> Then try launching the app again.
Linux:
Download the latest Claude-Usage-Widget-{version}-linux-x86_64.AppImage (Intel/AMD) or Claude-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:
> bash > sudo apt install libfuse2 >
Linux: Desktop Launcher & Autostart (optional)
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.
> 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.
git clone https://github.com/SlavomirDurej/claude-usage-widget.git
cd claude-usage-widget
npm install
npm start
Usage
First Launch
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
Widget Controls
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
System Tray
Right-click the tray icon for: Show/Hide, Refresh, Re-login, Settings, Exit.
Multi-Account Support (Advanced)
Launch with --profile= to run a fully isolated instance — its own session, cookies, and settings — so you can track two Claude accounts side by side without them interfering.
Example: claude-usage-widget --profile=work
This is a power-user feature, tested by us but not yet broadly validated by the community — if you hit issues, please open a GitHub Discussion.
Understanding the Display
Current Session & Weekly Limit
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%)
