claude-usage-widget/README.md

Claude Usage Widget

A beautiful, highly customizable Windows desktop widget that displays your Claude.ai usage statistics in real-time with system tray integration.

[SCREENSHOT: Main widget showing session and weekly usage]

Features

Core Features

• 🎯 Real-time Usage Tracking - Monitor both 5-hour session and 7-day weekly usage limits
• 📊 Visual Progress Bars - Clean, gradient progress indicators with customizable colors
• ⏱️ Countdown Timers - Circular timers showing time until session/weekly reset
• 🔄 Configurable Auto-refresh - Adjustable update interval (10-300 seconds)
• 🎨 Fully Customizable UI - Toggle any element on/off, customize all colors and theme
• 📍 Always on Top - Stays visible across all workspaces
• 🔒 Secure - Encrypted credential storage using electron-store

System Tray Integration

• 💾 Live Tray Icon - Real-time usage percentage displayed in system tray
• 🎨 Customizable Tray Colors - Independent color schemes for tray icon
• ⚙️ Tray Update Interval - Configurable refresh rate (10-300 seconds)
• 📊 Switchable Metrics - Display either session or weekly usage in tray
• 🔢 Toggle Percentage Text - Show/hide percentage number on tray icon

Advanced Customization

• 🎨 Theme Editor - Customize background gradients, text colors, borders, and title bar
• 🖼️ Element Visibility Controls - Show/hide any UI element independently:
  • Section labels (Current Session / Weekly Limit)
  • Progress bars
  • Percentage text
  • Countdown circles
  • Time remaining text
• 📏 Dynamic Resizing - Window automatically adjusts to fit visible elements
• 💎 Static or Gradient Colors - Choose between static colors or gradient progressions
• 🎯 Color Coding by Usage - Different colors for normal (0-74%), warning (75-89%), and danger (90-100%)

Application Settings

• 🚀 Start on System Boot - Automatically launch when Windows starts
• 🔽 Start Minimized - Begin in system tray without showing window
• 📌 Close to Tray - Minimize to tray instead of exiting application
• 💾 Persistent Window Position - Remembers and restores window location

Installation

Download Pre-built Release

1. Download the latest Claude-Usage-Widget-Setup.exe from Releases
2. Run the installer
3. Launch "Claude Usage Widget" from Start Menu

Build from Source

Prerequisites:

• Node.js 18+ (Download)
• npm (comes with Node.js)

Steps:

# Clone the repository
git clone https://github.com/yourusername/claude-usage-widget.git
cd claude-usage-widget

# Install dependencies
npm install

# Run in development mode
npm start

# Build installer for Windows
npm run build:win

The installer will be created in the dist/ folder.

Usage

First Launch

1. Launch the widget
2. The app will attempt to auto-login using stored credentials
3. If no credentials exist, click "Login to Claude"
4. A browser window will open - login to your Claude.ai account
5. The widget will automatically capture your session
6. Usage data will start displaying immediately

[SCREENSHOT: Login screen]

Widget Controls

Title Bar:

• Drag - Click and drag anywhere on the title bar to move the widget
• Settings Icon - Open the comprehensive settings panel
• Refresh Icon - Update usage data immediately
• Minimize - Hide to system tray
• Close - Minimize to tray or exit (depending on settings)

[SCREENSHOT: Widget with controls highlighted]

System Tray

Tray Icon:

• Displays real-time usage percentage
• Color changes based on usage level (normal/warning/danger)
• Switches between session and weekly usage (configurable in settings)
• Updates independently with configurable interval

Tray Menu (Right-click):

• Show/Hide Widget - Toggle main window visibility
• Refresh Usage - Update data immediately
• Re-login - Clear credentials and login again
• Settings - Open settings panel
• Exit - Quit application completely

[SCREENSHOT: System tray icon and menu]

Settings

Access settings by clicking the gear icon on the widget or via the system tray menu.

Main Window Settings

Colors

Customize progress bar colors with gradient or static options:

Static Color Mode:

• Enable "Use Static Color" toggle
• Choose a single color for the progress bar (ignores usage levels)

Gradient Mode (Default):

• Normal (0-74% usage) - Default: Purple gradient (#8b5cf6 → #a78bfa)
• Warning (75-89% usage) - Default: Orange gradient (#f59e0b → #fbbf24)
• Danger (90-100% usage) - Default: Red gradient (#ef4444 → #f87171)

Each level has independent start and end colors for smooth gradients.

[SCREENSHOT: Color customization panel]

Theme

Customize the entire widget appearance:

• Background Gradient - Start and end colors
• Text Colors - Primary and secondary text
• Title Bar - Background color and opacity (0-100%)
• Borders - Border color and opacity (0-100%)

[SCREENSHOT: Theme customization panel]

Update Interval

• Range: 10-300 seconds (default: 30 seconds)
• Controls how often the main widget refreshes usage data
• Lower values = more current data, higher API usage
• Slider with real-time value display

Current Session Elements

Control visibility of each element in the Current Session section:

• Show Current Session - Master toggle for entire section
• Show Label Text - "CURRENT SESSION" label
• Show Progress Bar - Usage progress bar
• Show Percentage Text - Usage percentage number
• Show Countdown Circle - Circular timer graphic
• Show Time Text - Time remaining until reset

[SCREENSHOT: Element visibility controls]

Weekly Limit Elements

Identical controls for the Weekly Limit section:

• Master toggle to show/hide entire section
• Individual toggles for label, bar, percentage, circle, and time

Example Configurations:

• Minimal: Just progress bars (hide everything else)
• Data-rich: All elements visible (default)
• Custom: Any combination you prefer

Tray Icon Settings

Display Mode

Choose which metric to display in the system tray:

• Session Usage (5-hour limit)
• Weekly Usage (7-day limit)

Update Interval

• Range: 10-300 seconds (default: 30 seconds)
• Independent from main widget update interval
• Tray icon updates on its own schedule

Show Percentage Text

• Toggle percentage number on/off in tray icon
• When disabled, shows only the colored ring

Colors

Separate color customization for tray icon:

• Static or gradient mode (same as main widget)
• Independent color schemes
• Normal/Warning/Danger levels

[SCREENSHOT: Tray icon settings]

Application Settings

Start on System Boot

• Automatically launch widget when Windows starts
• Registers with Windows startup items
• Disable to manually start the widget

Start Minimized

• Launch hidden in system tray
• Widget won't show window on startup
• Access via tray icon

Close to Tray

• When enabled: Clicking X minimizes to tray
• When disabled: Clicking X exits application
• Minimize button always goes to tray

[SCREENSHOT: Application settings]

Account

Log Out - Clears stored credentials and returns to login screen

Understanding the Display

Current Session (5-Hour Limit)

• Progress Bar - Visual representation of usage (0-100%)
• Percentage - Exact usage percentage
• Countdown Circle - Circular timer showing progress toward reset
• Time Remaining - Hours and minutes until session resets (e.g., "2h 34m")
• Color Coding:
  • Purple: Normal usage (0-74%)
  • Orange: High usage (75-89%)
  • Red: Critical usage (90-100%)

Weekly Limit (7-Day Rolling Window)

• Progress Bar - Weekly usage from 0-100%
• Percentage - Exact weekly usage percentage
• Countdown Circle - Progress toward weekly reset
• Time Remaining - Days/hours until weekly reset (e.g., "3d 5h")
• Same color coding as session usage

[SCREENSHOT: Usage display explanation with labels]

Window Behavior

Dynamic Resizing

• Window automatically resizes based on visible elements
• Shows only what you've enabled in settings
• Maintains minimum size for readability
• Cannot be manually resized smaller than content

Manual Resizing

• Drag edges to resize window
• Constraints: 320-600px width, 96-180px height
• Content stays centered at all sizes

Position Persistence

• Window position saved automatically when moved
• Restored on next launch
• Per-display awareness

Keyboard Shortcuts

Currently, the widget does not have keyboard shortcuts. This may be added in a future version.

Troubleshooting

"Login Required" keeps appearing

• Your Claude.ai session may have expired
• Click "Login to Claude" to re-authenticate
• Check that you're logging into the correct account
• Verify Claude.ai is accessible in your region

Widget not updating

• Check your internet connection
• Click the refresh button manually
• Ensure Claude.ai API is accessible
• Try increasing update interval if experiencing rate limits
• Re-login from system tray menu

Tray icon not showing/updating

• Check that "Show Percentage Text" is enabled to see text
• Verify update interval isn't too long
• Try changing display mode (session ↔ weekly)
• Restart the application

Window too small/elements cut off

• Check element visibility settings
• Enable more elements to expand window
• Window automatically sizes to fit enabled elements
• Reset to defaults if layout seems broken

Auto-start not working

• Verify "Start on System Boot" is enabled in settings
• Check Windows Task Manager > Startup tab
• May require administrator rights on some systems

Build errors

# Clear cache and reinstall
rm -rf node_modules package-lock.json
npm install

Privacy & Security

• Local Storage Only - Your session credentials are stored locally using encrypted electron-store
• No Third-Party Servers - No data is sent to any servers except Claude.ai official API
• Official API Only - Widget only communicates with Claude.ai API endpoints
• Secure Cookies - Session cookies stored using Electron's secure storage
• Open Source - All code is publicly available for audit

Technical Details

Built with:

• Electron 28.0.0
• Pure JavaScript (no framework overhead)
• Native Node.js APIs
• electron-store for encrypted secure storage
• axios for HTTP requests
• Canvas API for tray icon generation

API Endpoints:

https://claude.ai/api/organizations/{org_id}/usage
https://claude.ai/api/organizations

Storage Location:

%APPDATA%/claude-usage-widget/config.json (encrypted)

Configuration Keys:

• sessionKey - Encrypted Claude.ai session token
• organizationId - Your Claude organization UUID
• colorPreferences - Custom color settings
• traySettings - Tray icon configuration
• themeSettings - Widget theme preferences
• appSettings - Application behavior settings
• uiVisibility - Element visibility toggles
• windowPosition - Saved window location

Project Structure

claude-usage-widget/
├── main.js                  # Electron main process
├── preload.js              # IPC bridge (security)
├── package.json            # Dependencies and scripts
├── assets/
│   ├── icon.ico           # Application icon
│   └── logo.png           # Widget logo
└── src/
    └── renderer/
        ├── index.html     # Main widget UI
        ├── app.js         # Widget logic
        ├── styles.css     # Widget styles
        ├── settings.html  # Settings panel UI
        ├── settings.js    # Settings logic
        └── settings-styles.css  # Settings styles

Version History

v1.4.2 (Current)

• ✨ Added comprehensive UI element visibility controls
• ✨ Added system tray icon with live usage display
• ✨ Added customizable tray icon colors and update interval
• ✨ Added application settings (start on boot, start minimized, close to tray)
• ✨ Added theme customization (backgrounds, text colors, borders, opacity)
• ✨ Added configurable update intervals for UI and tray
• ✨ Added static color mode for progress bars
• ✨ Added dynamic window resizing based on visible elements
• 🎨 Improved settings organization with collapsible sections
• 🎨 Consistent typography and spacing throughout settings
• 🐛 Fixed element centering and responsive layout
• 🐛 Fixed timer container visibility handling

v1.4.1

• Added color customization
• Added settings panel
• Improved window position persistence

v1.4.0

• Added custom color themes
• Added settings window
• Remember window position

v1.3.0

• Initial public release
• Real-time usage tracking
• System tray support
• Auto-refresh functionality

Roadmap

Planned Features

• macOS support
• Linux support
• Notification alerts at usage thresholds
• Usage history graphs
• Export usage data (CSV/JSON)
• Multiple account support
• Keyboard shortcuts
• Mini mode (ultra-compact view)
• Desktop widget mode (frameless, always-on-desktop)
• Custom notification sounds

Completed

• Custom color themes
• Remember window position
• Settings panel
• System tray integration
• Tray icon with live usage
• Element visibility controls
• Theme customization
• Configurable update intervals
• Auto-start on boot
• Static color mode

Contributing

Contributions are welcome! Here's how you can help:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Guidelines

• Follow existing code style
• Test thoroughly before submitting PR
• Update README if adding features
• Add comments for complex logic

License

MIT License - feel free to use, modify, and distribute as needed.

See LICENSE file for full details.

Disclaimer

This is an unofficial tool and is not affiliated with, endorsed by, or connected to Anthropic or Claude.ai in any way.

• Use at your own risk and discretion
• No warranties or guarantees provided
• Not responsible for any issues arising from use
• May break if Claude.ai changes their API
• Respect Anthropic's Terms of Service

Support

If you encounter issues:

1. Check existing issues - Issues page
2. Create a new issue with:
   • Your Windows version
   • Widget version
   • Steps to reproduce
   • Error messages (if any)
   • Screenshots (if relevant)

Before reporting:

• Try restarting the widget
• Try re-logging in
• Check if Claude.ai is accessible in browser
• Verify you have the latest version

Acknowledgments

• Built for the Claude.ai community
• Inspired by the need for easy usage monitoring
• Thanks to all contributors and users

---

Made with ❤️ for the Claude.ai community

Star ⭐ this repo if you find it useful!