# Claude Code Balance Widget

**Version:** 1.0.0  
**Release Date:** July 8, 2025  
**Author:** Dalibor Votruba (Quadarax)  

A Windows desktop widget that monitors your Claude API balance and provides quick access to Anthropic Console billing information.

## 🎯 Features

- **System Tray Integration** - Runs quietly in the background with notification area icon
- **Transparent Overlay** - Modern glass-like appearance with drag-and-drop positioning
- **Multiple Authentication Methods** - Supports both API Key and Session Cookie authentication
- **Real-time Status** - Shows connection status and last update time
- **Quick Console Access** - One-click access to Anthropic Console billing page
- **Auto-refresh** - Automatically checks status every 5 minutes

## ⚠️ Important Limitations

**Anthropic does not provide a public API endpoint for account balance.** This widget can:
- ✅ Verify your API key is valid and working
- ✅ Test session cookie authentication
- ✅ Provide quick access to Console billing page
- ❌ **Cannot automatically retrieve your actual balance**

For API Key users, the widget displays "Check Console" and provides convenient links to manually check your balance.

## 🔧 System Requirements

- **OS:** Windows 10/11
- **Framework:** .NET 9.0
- **Architecture:** x64
- **Anthropic Account:** Console account with API access or valid session

## 🚀 Installation

1. Download the latest release from the releases page
2. Extract to your preferred location
3. Run `claudecodebalancewidget.exe`
4. Configure authentication in Settings

## ⚙️ Configuration

### API Key Method (Recommended)
1. Right-click system tray icon → **Settings**
2. Select **"API Key (Recommended)"** tab
3. Get your API key from [Anthropic Console](https://console.anthropic.com/) → Settings → API Keys
4. Enter the API key (starts with `sk-ant-api03-`)
5. Click **"Test API Key"** to verify
6. Click **OK** to save

### Session Cookie Method (Legacy)
1. Right-click system tray icon → **Settings**
2. Select **"Session Cookie (Legacy)"** tab
3. Go to [Anthropic Console Billing](https://console.anthropic.com/settings/billing)
4. Open Developer Tools (F12) → Application → Cookies
5. Copy the `sessionKey` cookie value
6. Enter in the widget and test

> **Note:** Session cookie method may not work due to enhanced security measures.

## 🎮 Usage

### System Tray Menu
- **Show/Hide** - Toggle widget visibility
- **Refresh Now** - Manual status refresh
- **Open Console Billing** - Direct link to billing page
- **Settings** - Configure authentication
- **About** - Version and help information
- **Exit** - Close application

### Widget Display
- **Green ($XX.XX)** - Balance above $5
- **Yellow ($XX.XX)** - Balance $1-$5
- **Red ($XX.XX)** - Balance below $1
- **Blue "Check Console"** - API key valid, check balance manually
- **Red "Error"** - Authentication or connection error

### Mouse Controls
- **Left Click + Drag** - Move widget position
- **Left Click** (when showing "Check Console") - Open billing page
- **Right Click** - Show context menu

## 🔍 Troubleshooting

### Forbidden Error (Session Cookie)
- Anthropic has enhanced security measures
- Session cookies may no longer work
- **Solution:** Switch to API Key authentication

### API Key Issues
- Verify key starts with `sk-ant-api03-`
- Check billing is set up in Console
- Ensure you have available credits
- Verify key has proper permissions

### Connection Errors
- Check your internet connection
- Verify Anthropic services are online
- Try refreshing manually
- Check firewall/antivirus settings

## 📁 File Structure

```
ClaudeCodeBalanceWidget/
├── claudecodebalancewidget.exe     # Main executable
├── ClaudeCodeBalanceWidget.ico     # Application icon
└── README.md                       # This file

Configuration stored in:
%APPDATA%/ClaudeBalanceMonitor/
├── config.txt                      # Authentication settings
└── position.txt                    # Widget position
```

## 🛠️ Development

**Technology Stack:**
- .NET 9.0 Windows Forms
- C# with modern language features
- HTTP client for API communication
- Regular expressions for HTML parsing

**Building from Source:**
```bash
git clone <repository-url>
cd ClaudeCodeBalanceWidget
dotnet build --configuration Release
```

**Project Structure:**
```
├── MainForm.cs                     # Main application logic
├── SettingsForm.cs                 # Configuration dialog
├── EnhancedSettingsForm.cs         # Advanced settings with tabs
├── Program.cs                      # Application entry point
└── ClaudeCodeBalanceWidget.csproj  # Project configuration
```

## 📋 Authentication Methods Comparison

| Method | Reliability | Setup Difficulty | Auto-Balance | Security |
|--------|-------------|------------------|--------------|----------|
| **API Key** | ✅ High | 🟡 Medium | ❌ No* | ✅ High |
| **Session Cookie** | ❌ Low | 🟢 Easy | ❌ No | 🟡 Medium |

*No automatic balance retrieval due to API limitations

## 🔗 Links

- **Anthropic Console:** https://console.anthropic.com/
- **API Documentation:** https://docs.anthropic.com/
- **Support:** https://support.anthropic.com/
- **Claude AI:** https://claude.ai/

## 📄 License

This is an unofficial tool not affiliated with Anthropic. Use at your own risk.

**Copyright © 2025 Quadarax - Dalibor Votruba**

## 🔄 Version History

### v1.0.0 (July 8, 2025)
- Initial release
- API Key and Session Cookie authentication
- System tray integration
- Transparent overlay widget
- Drag-and-drop positioning
- Auto-refresh functionality
- Enhanced error handling
- Quick Console access

---

> **Disclaimer:** This is an unofficial tool. Anthropic may change their authentication methods or block automated access at any time. Always keep your API keys secure and never share them.