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](https://github.com/SlavomirDurej/claude-usage-widget/releases)
2. Run the installer
3. Launch "Claude Usage Widget" from Start Menu

### Build from Source

**Prerequisites:**
- Node.js 18+ ([Download](https://nodejs.org))
- npm (comes with Node.js)

**Steps:**

```bash
# 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
```bash
# 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
- [x] Custom color themes
- [x] Remember window position
- [x] Settings panel
- [x] System tray integration
- [x] Tray icon with live usage
- [x] Element visibility controls
- [x] Theme customization
- [x] Configurable update intervals
- [x] Auto-start on boot
- [x] 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](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](../../issues)
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!**