A native macOS menu bar application for real-time monitoring of Claude AI usage limits English • Español • Français • Deutsch • Italiano • Português • 日本語 • 한국어 Download Latest Release (v2.3.0) macOS 14.0+ (Sonoma) | ~4 MB | Native Swift/SwiftUI | Officially Signed Claude Usage Tracker is a lightweight, native macOS menu bar application that provides real-ti
Add this skill
npx mdskills install hamed-elfayome/claude-usage-trackerWell-documented macOS menu bar app for Claude usage tracking, but not an AI agent skill
1# Claude Usage Tracker23<div align="center">4 <img src=".github/cover.jpg" alt="Claude Usage Tracker" width="100%">56 **A native macOS menu bar application for real-time monitoring of Claude AI usage limits**78 9 10 11 12 13 1415 <sub>🇬🇧 English • 🇪🇸 Español • 🇫🇷 Français • 🇩🇪 Deutsch • 🇮🇹 Italiano • 🇵🇹 Português • 🇯🇵 日本語 • 🇰🇷 한국어</sub>1617 ### [Download Latest Release (v2.3.0)](https://github.com/hamed-elfayome/Claude-Usage-Tracker/releases/latest/download/Claude-Usage.zip)1819 <sub>macOS 14.0+ (Sonoma) | ~4 MB | Native Swift/SwiftUI | Officially Signed</sub>2021 <a href="https://www.buymeacoffee.com/hamedelfayome" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" height="40"></a>22</div>2324---2526## Overview2728Claude Usage Tracker is a lightweight, native macOS menu bar application that provides real-time monitoring of your Claude AI usage limits. Built entirely with Swift and SwiftUI, it offers a clean, intuitive interface to track your 5-hour session window, weekly usage limits, and Opus-specific consumption.2930### Key Capabilities3132- **Multi-Profile Support**: Manage unlimited Claude accounts with isolated credentials and settings33- **Multi-Profile Display**: Monitor all profiles simultaneously in the menu bar (NEW in v2.3.0)34- **Claude Code Integration**: Sync CLI accounts and auto-switch credentials when changing profiles35- **Real-Time Monitoring**: Track session, weekly, and API console usage per profile36- **Customizable Interface**: 5 icon styles + monochrome mode + remaining/used percentage toggle37- **Smart Automation**: Auto-start sessions (per-profile background service), threshold notifications38- **Developer Tools**: Terminal statusline integration with automatic profile updates39- **Privacy-First**: Local storage, no telemetry, no cloud sync40- **Native Performance**: Lightweight Swift/SwiftUI design for macOS4142<div align="center">43 <img src=".github/icon.jpg" alt="Menu Bar Icon" height="180">44 <img src=".github/popover.png" alt="Popover Interface" width="200">4546 <sub>Menu bar icon and detailed usage popover</sub>4748 <img src=".github/statusline.png" alt="Claude Code Statusline">49 <br>50 <sub>Live terminal statusline showing directory, branch, and color-coded usage</sub>51</div>5253---5455## What's New5657- **v2.3.0 - Multi-Profile Menu Bar Display (2026-01-23)**:58 - **Multi-profile menu bar display**: Monitor all your Claude accounts simultaneously in the menu bar59 - **Remaining vs. used percentage**: Choose to display remaining budget instead of used percentage60 - **Unified usage calculations**: Centralized logic with intelligent color adaptation61 - **Enhanced icon rendering**: Per-profile icons with independent styling and settings6263- **v2.2.3** – Improved setup wizard with smart banners64- **v2.2.2** – CLI OAuth authentication fallback, simplified auto-start65- **v2.2.0** – Multi-profile management, CLI integration, Korean language66- **v2.1.2** – Statusline improvements, organization ID optimization67- **v2.1.1** – Session timer countdown in menu bar68- **v2.1.0** – 3-step setup wizard, smart organization preservation69- **v2.0.0** – Apple code signing, automatic updates, Keychain security7071**[View Full Release History](CHANGELOG.md)**7273---7475## Getting Started7677### Prerequisites7879Before installing Claude Usage Tracker, ensure you have:8081- **macOS 14.0 (Sonoma) or later** - Check: Apple menu → About This Mac82- **Active Claude AI account** - Sign up at [claude.ai](https://claude.ai)8384**Authentication** (choose one method):85- **Easiest**: [Claude Code](https://claude.com/claude-code) installed and logged in - App automatically uses CLI credentials (v2.2.2+)86- **Manual**: Web browser access to extract session key from claude.ai (Chrome, Safari, Firefox, etc.)8788**Note**: For terminal statusline integration, you'll still need to manually configure a session key even if using Claude Code OAuth8990### Installation9192#### Option 1: Homebrew (Recommended)9394```bash95brew install --cask hamed-elfayome/claude-usage/claude-usage-tracker96```9798Or tap first, then install:99100```bash101brew tap hamed-elfayome/claude-usage102brew install --cask claude-usage-tracker103```104105**Note**: Starting with v2.0.0, the app is officially signed with an Apple Developer certificate. No security workarounds needed!106107**To update**:108```bash109brew upgrade --cask claude-usage-tracker110```111112Or use the built-in automatic update feature (Settings → Updates).113114**To uninstall**:115```bash116brew uninstall --cask claude-usage-tracker117```118119#### Option 2: Direct Download120121**[Download Claude-Usage.zip](https://github.com/hamed-elfayome/Claude-Usage-Tracker/releases/latest/download/Claude-Usage.zip)**1221231. Download the `.zip` file from the link above1242. Extract the zip file (double-click or use Archive Utility)1253. Drag `Claude Usage.app` to your Applications folder1264. Double-click to launch - that's it!127128**v2.0.0+ Note**: The app is now officially signed with an Apple Developer certificate. You can install and run it like any other Mac application - no security warnings or workarounds needed.129130**Automatic Updates**: Once installed, the app will automatically check for updates and notify you when new versions are available (Settings → Updates).131132#### Option 3: Build from Source133134```bash135# Clone the repository136git clone https://github.com/alexbartok/Claude-Usage-Tracker.git137cd Claude-Usage-Tracker138139# Open in Xcode140open "Claude Usage.xcodeproj"141142# Build and run (⌘R)143```144145### Quick Start Guide146147#### Option A: Automatic Setup with Claude Code (Easiest)148149**New in v2.2.2**: If you have Claude Code installed and logged in, the app works automatically!1501511. **Install Claude Code** (if not already installed)152 - Download from [claude.com/claude-code](https://claude.com/claude-code)153 - Log in using `claude login`1541552. **Launch Claude Usage Tracker**156 - The app automatically detects your Claude Code Account157 - No manual configuration needed!1581593. **Verify It's Working**160 - Click the menu bar icon161 - You should see your usage statistics immediately162163#### Option B: Manual Setup with Session Key164165If you prefer manual configuration or don't use Claude Code:166167**Step 1: Extract Your Session Key**1681691. **Open Claude AI**170 - Navigate to [claude.ai](https://claude.ai) in your browser171 - Make sure you're logged in1721732. **Open Developer Tools**174 - **Chrome/Edge**: Press `F12` or `Cmd+Option+I` (macOS) / `Ctrl+Shift+I` (Windows)175 - **Safari**: Enable Developer menu in Preferences → Advanced, then press `Cmd+Option+I`176 - **Firefox**: Press `F12` or `Cmd+Option+I` (macOS) / `Ctrl+Shift+I` (Windows)1771783. **Navigate to Cookies**179 - Go to: **Application** tab (Chrome/Edge) or **Storage** tab (Firefox)180 - Expand: **Cookies** → **https://claude.ai**181 - Find: `sessionKey` cookie182 - Copy: The value (starts with `sk-ant-sid01-...`)183184**Step 2: Configure Session Key**1851861. **Click the menu bar icon** and select "Settings"1872. **Navigate to "Personal Usage"** tab1883. **3-Step Wizard** guides you through setup:189 - **Step 1**: Paste your session key and click "Test Connection"190 - **Step 2**: Select your Claude organization from the list191 - **Step 3**: Review and click "Save Configuration"1924. **Wait for confirmation** (success message appears)193194**Step 3: Verify It's Working**1951961. **Check Menu Bar**: You should see the Claude Usage icon in your menu bar1972. **Click the Icon**: Popover appears showing your usage statistics1983. **View Data**: Session usage, weekly usage, and reset timers should display199200**Success!** The app is now monitoring your Claude usage.201202#### Next Steps203204- **Customize Icon**: Go to Settings → Appearance to choose your preferred menu bar style205- **Su**: Go to Settings → Appearance to choose your preferred menu bar style206- **Enable Notifications**: Settings → Notifications to get threshold alerts207- **Auto-Start Sessions**: Settings → Session Management to enable automatic session initialization208- **Terminal Integration**: Settings → Claude Code to set up statusline (requires session key configuration)209210---211212## Advanced Configuration213214### Manual Session Key Setup215216If you prefer to configure the session key manually instead of using the setup wizard:217218```bash219# Create session key file220echo "sk-ant-sid01-YOUR_SESSION_KEY_HERE" > ~/.claude-session-key221222# Set secure permissions (important for security)223chmod 600 ~/.claude-session-key224```225226After creating the file, launch the app and it will automatically detect the session key.227228---229230## Multi-Profile Management231232**New in v2.2.0**: Claude Usage Tracker now supports unlimited profiles, allowing you to manage multiple Claude accounts seamlessly with automatic credential switching.233234**New in v2.3.0**: Multi-profile menu bar display lets you monitor all your profiles simultaneously!235236### Features237238#### Profile Management239- **Unlimited Profiles**: Create as many profiles as needed for different Claude accounts240- **Multi-Profile Display**: Show all profiles in the menu bar at once (v2.3.0)241 - Toggle between Single mode (active profile only) and Multi mode (all profiles)242 - Each profile displays with its own icon style and settings243 - Click any profile icon to view its usage details244 - Independent refresh rates per profile245- **Fun Auto-Names**: Profiles auto-generate with names like "Quantum Llama", "Sneaky Penguin", "Turbo Sloth"246- **Custom Names**: Rename profiles to whatever you prefer247- **Quick Switching**: Switch profiles instantly via popover dropdown or settings sidebar248- **Profile Badges**: Visual indicators show which profiles have Claude.ai credentials and CLI accounts249250#### Claude Code CLI Integration251- **One-Click Sync**: Sync your currently logged-in Claude Code account to a profile252- **Automatic Switching**: When you switch profiles, CLI credentials automatically update253- **Credential Display**: View masked access tokens and subscription type254- **Smart Re-Sync**: Credentials automatically refresh before profile switches to capture CLI changes255- **Per-Profile CLI**: Each profile can have its own Claude Code account or share the system account256257#### Per-Profile Settings258Each profile has isolated settings:259- **Credentials**: Separate Claude.ai session keys, API keys, and organization IDs260- **Appearance**: Independent icon styles and monochrome mode261- **Refresh Interval**: Custom refresh rates (5-300 seconds)262- **Auto-Start Sessions**: Enable/disable per profile263- **Notifications**: Independent threshold alerts (75%, 90%, 95%)264- **Usage Data**: Tracked separately per profile265266#### Profile Switcher267Access profile switcher in multiple places:268- **Popover Header**: Dropdown menu with profile badges269- **Settings Sidebar**: Active profile picker with visual indicators270- **Manage Profiles Tab**: Full profile management interface271272#### How to Use2732741. **Create Profiles**:275 - Go to Settings → Manage Profiles276 - Click "Create New Profile"277 - Auto-generates a fun name or enter your own2782792. **Configure Credentials**:280 - Switch to desired profile in sidebar281 - Go to Claude.AI / API Console / CLI Account tabs282 - Enter credentials (isolated per profile)2832843. **Sync Claude Code** (Optional):285 - Log in to Claude Code in terminal286 - Open Settings → CLI Account287 - Click "Sync from Claude Code"288 - Now when you switch profiles, CLI credentials auto-update!2892904. **Switch Profiles**:291 - Click popover dropdown292 - Or use settings sidebar picker293 - CLI credentials apply automatically294295296---297298## Features299300### Installation & Updates301- **Official Apple Code Signing**: Professionally signed application - installs like any Mac app302- **Automatic Updates**: Built-in update system powered by Sparkle framework303- **One-Click Installation**: No security workarounds or manual approvals needed304- **Update Notifications**: Get notified when new versions are available305306### Usage Tracking & Monitoring307- Real-time monitoring of 5-hour session, weekly limits, and Opus-specific usage308- API console usage tracking for comprehensive visibility309- Extra usage cost tracking for Claude Extra subscribers310- Color-coded indicators (green/orange/red) based on consumption levels311- Smart countdown timers for session and weekly resets312313### Menu Bar & Interface314- **5 Customizable Icon Styles**: Battery, Progress Bar, Percentage Only, Icon with Bar, Compact315- **Multi-Metric Icons**: Display separate icons for session, weekly, and api usage simultaneously316- **Monochrome Mode**: Optional black & white aesthetic317- **Interactive Popover**: One-click access with detachable floating window capability318- **Live Status Indicator**: Real-time Claude system status from status.claude.com319- **Multi-Language Support**: 6 languages (English, Spanish, French, German, Italian, Portuguese)320- Adaptive colors for light/dark mode321322### Automation & Intelligence323- **Auto-Start Sessions**: Automatically initialize new sessions when usage resets to 0%324- **Smart Notifications**: Threshold alerts at 75%, 90%, and 95% usage325- **Network Monitoring**: Auto-detect connectivity changes and handle offline scenarios326- **Launch at Login**: System-level auto-start option327- **Configurable Refresh**: Set intervals from 5 to 120 seconds328- Session reset and auto-start confirmations329330### Developer Integration331- **Claude Code Terminal Statusline**: Real-time usage in your terminal332- Customizable components: directory, git branch, usage percentage, progress bar, reset timer333- One-click automated installation334- Live preview before applying changes335336### Security & Privacy337- **macOS Keychain Storage**: Session keys stored in macOS Keychain (most secure option)338- **Automatic Migration**: Seamless migration from old storage methods339- **Apple Code Signed**: Verified by Apple for enhanced security and trust340- **Advanced Error Handling**: Professional error system with user-friendly recovery341- **Robust Validation**: Session key and API endpoint validation342- Local storage with no cloud sync343- Zero telemetry or tracking344- HTTPS-only communication with Claude API345346### Advanced Capabilities347- Multi-screen support348- First-run guided setup wizard349- Protocol-based modular architecture350- Persistent settings with App Groups351- Comprehensive test coverage352353---354355## Usage356357### Menu Bar Interface358359Click the menu bar icon to access:360361- **Session Usage**: 5-hour rolling window percentage and reset time362- **Weekly Usage**: Overall weekly consumption across all models363- **Opus Usage**: Weekly Opus-specific usage (if applicable)364- **Quick Actions**: Refresh, Settings, and Quit365366### Settings367368Access comprehensive settings through the menu bar popover → Settings button. The app features a modern sidebar interface with profile switcher and organized tabs:369370### Profile-Specific Settings371372#### Profile Switcher (Sidebar)373- **Quick Profile Selection**: Dropdown to switch between profiles instantly374- **Profile Badges**: Visual indicators for Claude.ai 🔵 and CLI ✅ credentials375- **Active Profile Display**: Shows currently selected profile376377#### Claude.AI (Credentials)378Configure your Claude.ai personal account:379- **3-Step Setup Wizard**: Guided session key configuration380 - Non-destructive connection testing381 - Visual organization selector382 - Configuration summary with preview383- **Smart Updates**: Organization preserved when re-entering same key384- **Quick Access**: One-click link to claude.ai385386#### API Console (Credentials)387Configure API console usage tracking:388- **API Session Key**: Set your API authentication key389- **Organization ID**: Configure organization for API tracking390- **Dual Tracking**: Monitor both web and API usage simultaneously391- **API Billing**: View API console usage costs392393#### CLI Account (Credentials)394Sync Claude Code CLI credentials:395- **One-Click Sync**: Copy currently logged-in Claude Code account to profile396- **Credential Display**: View masked access token and subscription type397- **Auto-Switch**: Credentials automatically update when changing profiles398- **Remove Sync**: Unlink CLI account from profile399400#### Appearance401Customize menu bar icon per profile:402- **Icon Style Selection**: Choose from 5 different display modes403 - Battery Style (classic indicator with fill)404 - Progress Bar (horizontal bar with percentage)405 - Percentage Only (text-only minimalist)406 - Icon with Bar (Claude icon + progress)407 - Compact (space-efficient)408- **Monochrome Mode**: Toggle black & white icon style409- **Percentage Display Mode** (NEW in v2.3.0): Toggle between used/remaining percentage410 - Show "75% used" or "25% remaining" - your choice411 - Color coding automatically adapts (green for high remaining, red for low)412 - Helps focus on budget left rather than budget spent413- **Live Preview**: See changes in real-time before applying414415#### General (Profile Settings)416Per-profile behavior configuration:417- **Refresh Interval**: Configure auto-refresh rate (5-300 seconds)418- **Auto-Start Sessions**: Enable/disable automatic session initialization on reset419- **Model Selection**: Uses the most cost-effective model available420- **Notifications**: Per-profile threshold alerts (75%, 90%, 95%)421422### App-Wide Settings423424#### Manage Profiles425Create and manage multiple profiles:426- **Create Profiles**: Add new profiles with fun auto-generated names427- **Rename Profiles**: Customize profile names428- **Delete Profiles**: Remove unused profiles (minimum 1 required)429- **Profile List**: View all profiles with credential status indicators430- **Display Mode Toggle** (NEW in v2.3.0): Switch between Single and Multi mode431 - Single Mode: Show only the active profile in menu bar432 - Multi Mode: Show all profiles simultaneously in menu bar433434#### Language435Application language preferences:436- **Language Selection**: Choose from 8 supported languages437- **Live Updates**: Interface updates immediately when language changes438- Supported: English, Spanish, French, German, Italian, Portuguese, Japanese, Korean439440#### Claude Code (Statusline)441Terminal integration (app-wide):442- **Component Selection**: Choose what to display (directory, branch, usage, progress bar, reset time)443- **Live Preview**: See exact statusline format before installing444- **One-Click Install**: Automated script installation to `~/.claude/`445- **Automatic Updates**: Statusline updates when switching profiles446- See [Claude Code Integration](#claude-code-integration) section for detailed setup447448#### Updates449Automatic update configuration:450- **Automatic Update Checking**: Configure how often to check for updates451- **Update Notifications**: Get notified when new versions are available452- **One-Click Installation**: Download and install updates with a single click453- **Release Notes**: View what's new in each update454455#### About456Application information:457- **Version Information**: Current app version458- **Credits**: Contributors and acknowledgments459- **Links**: GitHub repository, issue tracker, documentation460461462## Claude Code Integration463464Bring real-time Claude usage monitoring directly into your terminal with Claude Code statusline integration! Display your current usage percentage, git branch, and working directory without leaving your development workflow.465466### What is Claude Code?467468[Claude Code](https://claude.com/claude-code) is Anthropic's official CLI tool for interacting with Claude AI directly from your terminal. The statusline feature allows you to display custom information at the bottom of your terminal window.469470<div align="center">471 <img src=".github/statusline.png" alt="Claude Code Statusline in Action" width="90%">472 <br>473 <sub>Example: Terminal statusline with all components enabled</sub>474</div>475476### Setup Instructions477478#### Prerequisites4794801. **Claude Code installed**: Download from [claude.com/claude-code](https://claude.com/claude-code)4812. **Session key configured**: Must be manually configured in the Personal Usage tab (Claude Code OAuth doesn't work for statusline - it requires direct session key)482483#### Installation Steps4844851. **Open Claude Usage Tracker Settings**486 - Click the menu bar icon487 - Click "Settings"488 - Navigate to the "Claude Code" tab4894902. **Choose Your Components**491 - Toggle on/off the components you want to see:492 - **Directory name**: Shows current working directory493 - **Git branch**: Displays current branch with ⎇ icon494 - **Usage statistics**: Shows session percentage with color coding495 - **Progress bar**: Visual 10-segment indicator (optional when usage is enabled)4964973. **Preview Your Statusline**498 - The live preview shows exactly how it will appear499 - Example: `claude-usage │ ⎇ main │ Usage: 25% ▓▓░░░░░░░░`5005014. **Apply Configuration**502 - Click "Apply" button503 - Scripts will be installed to `~/.claude/`504 - Claude Code's `settings.json` will be updated automatically5055065. **Restart Claude Code**507 - Close and reopen your Claude Code terminal508 - The statusline will appear at the bottom of your terminal window509510### What Gets Installed511512The setup automatically creates:513514- `~/.claude/fetch-claude-usage.swift`: Swift script that fetches usage data from Claude API515- `~/.claude/statusline-command.sh`: Bash script that builds the statusline display516- `~/.claude/statusline-config.txt`: Configuration file with your component preferences517- `~/.claude/settings.json`: Updated with statusline command (or created if doesn't exist)518519All scripts are set with secure permissions (755) and only read your existing session key file.520521### Customization522523#### Available Components524525| Component | Description | Example |526|-----------|-------------|---------|527| Directory | Current directory name | `claude-usage` |528| Git Branch | Active git branch | `⎇ main` |529| Usage | Session percentage | `Usage: 25%` |530| Progress Bar | 10-segment visual indicator | `▓▓░░░░░░░░` |531| Reset Time | When session resets | `→ Reset: 3:45 PM` |532533#### Color Coding534535Usage percentage is color-coded with a 10-level gradient:536- **0-10%**: Dark green537- **11-30%**: Green shades538- **31-50%**: Yellow-green transitioning to olive539- **51-70%**: Yellow to orange540- **71-90%**: Dark orange to red541- **91-100%**: Deep red542543#### Disabling Statusline544545To remove the statusline:5461. Open Claude Usage Tracker Settings → Claude Code tab5472. Click "Reset" button5483. Restart Claude Code549550This removes the statusline configuration but keeps the scripts installed for easy re-enabling.551552### Troubleshooting553554#### Statusline Not Appearing5555561. Verify Claude Code is installed and working5572. Check that you restarted Claude Code after applying5583. Ensure session key is valid in General settings tab5594. Check that `~/.claude/settings.json` exists and has the statusline configuration560561#### Shows "Usage: ~"562563This indicates the Swift script couldn't fetch usage data:564- Verify your session key is valid565- Check that `~/.claude-session-key` exists566- Ensure you're connected to the internet567- Try refreshing your session key from claude.ai568569#### Permission Issues570571If scripts can't be executed:572```bash573chmod 755 ~/.claude/fetch-claude-usage.swift574chmod 755 ~/.claude/statusline-command.sh575```576577### Example Statuslines578579With all components enabled:580```581my-project │ ⎇ feature/new-ui │ Usage: 47% ▓▓▓▓▓░░░░░ → Reset: 4:15 PM582```583584Minimal (usage only):585```586Usage: 12% ▓░░░░░░░░░587```588589Directory and branch only:590```591backend-api │ ⎇ develop592```593594## Architecture595596### Technology Stack597598- **Language**: Swift 5.0+599- **UI Framework**: SwiftUI 5.0+600- **Platform**: macOS 14.0+ (Sonoma)601- **Architecture**: MVVM with Protocol-Oriented Design602- **Storage**: UserDefaults with App Groups603- **Networking**: URLSession with async/await604- **Design Patterns**: Coordinator pattern, Protocol-based services, Modular components605606## API Integration607608The application integrates with multiple Claude API endpoints for comprehensive usage tracking:609610### Web Usage Endpoint611612```613GET https://claude.ai/api/organizations/{org_id}/usage614```615616**Authentication**: Session cookie (`sessionKey`) from claude.ai617618**Response Structure**:619- `five_hour`: 5-hour session usage data620 - `utilization_pct`: Usage percentage (0-100)621 - `reset_at`: ISO 8601 timestamp for next reset622- `seven_day`: Weekly usage across all models623 - `utilization_pct`: Weekly usage percentage624- `seven_day_opus`: Opus-specific weekly usage625 - `utilization_pct`: Opus weekly percentage626- `extra_usage`: Claude Extra cost tracking (if applicable)627 - `current_spending`: Amount spent628 - `budget_limit`: Maximum allowed spending629630### API Console Endpoint631632```633GET https://api.anthropic.com/v1/organization/{org_id}/usage634```635636**Authentication**: API Key (`x-api-key` header)637638**Response Structure**:639- API console usage statistics640- Billing information641- Rate limits and quotas642643### Dual Tracking644645The app can simultaneously monitor both web (claude.ai) and API console usage, providing complete visibility into your Claude consumption across all access methods.646647## Security648649- **macOS Keychain**: Session keys stored securely in macOS Keychain (most secure storage available)650- **Automatic Migration**: v2.0+ automatically migrates session keys from older storage methods to Keychain651- **Apple Code Signed**: Officially signed with Apple Developer certificate for verified authenticity652- **Secure Updates**: Automatic updates delivered over HTTPS with code signature verification653- **No Cloud Sync**: All data remains local to your machine654- **No Telemetry**: Zero tracking or analytics655- **Advanced Error Handling**: Robust error system with user-friendly recovery656- **Session Key Validation**: Comprehensive validation of API credentials657- **Network**: HTTPS-only communication with claude.ai and Anthropic API658659## Troubleshooting660661### Application Not Connecting6626631. Verify your session key is valid6642. Check that you're logged into claude.ai in your browser6653. Try extracting a fresh session key6664. Ensure you have an active internet connection667668### 403 Permission Errors669670If you see "Unauthorized" or 403 errors:6711. Open Settings → Personal Usage6722. Use the 3-step wizard to reconfigure:673 - Test your session key674 - Select the correct organization675 - Save configuration6763. The wizard will preserve your organization selection when updating keys677678### Menu Bar Icons Showing Zero679680If icons briefly flash to zero during refresh:681- This has been fixed in v2.1.0+682- Update to the latest version for smooth refresh experience683- Old data now stays visible until new data arrives684685### Menu Bar Icon Not Appearing6866871. Check System Settings → Desktop & Dock → Menu Bar6882. Restart the application6893. Check Console.app for error messages690691### Session Key Expired692693Session keys may expire after a period of time. Extract a new key from claude.ai and update it in Settings → Personal Usage using the wizard.694695### Updates Not Working696697If automatic updates aren't working:6986991. Check Settings → Updates to ensure automatic checking is enabled7002. Verify you're running v2.0.0 or later (earlier versions don't have auto-update)7013. Check your internet connection7024. Manually download the latest version from GitHub if needed703704## Contributors705706<img src="https://contrib.rocks/image?repo=hamed-elfayome/Claude-Usage-Tracker" alt="Contributors" height="30px" />707708This project is built for the community — everyone is welcome709710## Contributing711712Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.713714### Development Setup7157161. Fork the repository7172. Create your feature branch (`git checkout -b feature/AmazingFeature`)7183. Commit your changes (`git commit -m 'Add some AmazingFeature'`)7194. Push to the branch (`git push origin feature/AmazingFeature`)7205. Open a Pull Request721722### Code Style723724- Follow Swift API Design Guidelines725- Use SwiftUI best practices726- Maintain MVVM architecture727- Add comments for complex logic728- Write descriptive commit messages729730## License731732This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.733734## Acknowledgments735736- Built with Swift and SwiftUI737- Designed for macOS Sonoma and later738- Uses Claude AI's usage API739- Inspired by the need for better usage visibility740741## Disclaimer742743This application is not affiliated with, endorsed by, or sponsored by Anthropic PBC. Claude is a trademark of Anthropic PBC. This is an independent third-party tool created for personal usage monitoring.744745## AI Transparency746747This project is developed using AI-assisted workflows (primarily Claude Code via Happy). We believe in transparent collaboration between human developers and AI tools.748749---750751<div align="center">752 <sub>Built for the Claude AI community</sub>753</div>754
Full transparency — inspect the skill content before installing.