Monitor your Claude AI usage directly from the macOS menu bar.

This is a fork of Stats with added Claude AI usage monitoring.

# Uninstall original Stats if installed
brew uninstall --cask stats 2>/dev/null

brew tap solbish/tap
brew install --cask solbish/tap/stats
xattr -cr /Applications/Stats.app

Download Stats.dmg, open it, move to Applications, then run:

xattr -cr /Applications/Stats.app

Stats is supported on the released macOS version starting from macOS 12 (Monterey).

• 5-Hour Usage - Track your rolling 5-hour usage limit with real-time countdown
• 7-Day Usage - Monitor your weekly usage quota
• 24-Hour History Chart - Visualize usage patterns over time
• Peak Hours Indicator - Know when Claude is busiest (8 AM - 2 PM ET weekdays)
• Best Time Analysis - Find optimal times to use Claude based on historical data
• Multiple Widgets - Mini, Line Chart, Bar Chart, Pie Chart display options

The Claude module displays in your menu bar showing current 5-hour utilization.

Click the menu bar icon to see detailed usage information:

• 5-hour and 7-day usage bars with percentages
• Reset countdowns for each limit
• Model breakdown (Opus/Sonnet usage)
• 24-hour history chart
• Peak hours status
• Best time recommendations

The 24-hour history chart highlights peak hours (8 AM - 2 PM ET weekdays) as shaded areas. The status bar shows current off-peak/peak state with a countdown timer to the next change.

Configure authentication and update intervals.

The Claude module supports two authentication methods. Claude.ai Web is the primary method with more frequent updates.

This method uses browser cookies to fetch usage data directly from claude.ai.

Install the "Cookies Extractor" extension for Chrome/Edge:

• Chrome Web Store
• Or search "Cookies Extractor" in your browser's extension store

1. Go to claude.ai and log in
2. Click the Cookies Extractor extension icon in your browser toolbar
3. Click "Copy as JSON Cookie"

1. Open Stats settings (click the Stats icon in menu bar > Settings)
2. Navigate to the Claude module
3. Click "Import from Clipboard"
4. You should see "Import Successful" confirmation

The status will change from "Not configured" to "OK" with the last fetch time.

Choose how often to refresh data:

• 10 seconds (for active monitoring)
• 30 seconds
• 1 minute (default)
• 2 minutes
• 5 minutes

If you use the Claude Code CLI, you can import tokens from your Keychain.

1. Install Claude Code CLI: npm install -g @anthropic-ai/claude-code
2. Log in: claude login

1. Open Stats settings > Claude module
2. In the "Claude Code (fallback)" section, click "Import from Keychain"
3. Grant Keychain access if prompted

• 1 minute
• 2 minutes
• 5 minutes (default)
• 10 minutes

Note: Claude Code method has a longer default interval because API rate limits are more strict.

• 5-Hour Reset: Rolling window - resets portion used 5 hours ago
• 7-Day Reset: Weekly quota - resets portion used 7 days ago

Claude experiences higher load during:

• Peak: 8 AM - 2 PM ET, Monday-Friday
• Off-Peak: All other times

The indicator shows:

• Current status (PEAK/off-peak)
• Time until status changes

Based on your usage history, the module analyzes and recommends hours with lowest average usage.

Choose your preferred menu bar display:

Configure widgets in Stats settings > Claude > Widgets.

1. Ensure you're logged into claude.ai in your browser
2. Try re-exporting cookies with "Copy as JSON Cookie"
3. Make sure clipboard contains the JSON before clicking Import

Your session token has expired. Re-export cookies from your browser.

Increase the update interval in settings to reduce API calls.

1. Ensure Claude CLI is installed: which claude
2. Ensure you're logged in: claude status
3. Check Keychain Access has the claude credentials

1. Check the "Last updated" time in the popup
2. Verify internet connection
3. Try clearing and re-importing credentials

• Credentials are stored in macOS Keychain (encrypted)
• No data is sent to third parties
• All communication is directly with claude.ai
• Session tokens are masked in the UI (only last 8 characters shown)

macOS 26 introduced a new privacy control under System Settings → Menu Bar. Apps must be explicitly allowed there to display menu bar items. If Stats is running with at least one module active and one widget enabled, but none of its icons show up in the menu bar, this is almost certainly the cause. More details you can find here.

Solution: open System Settings → Menu Bar and toggle Stats ON.

Due to a problem with high data load in the system process (chronod) responsible for communication between the app and widgets, communication is disabled by default on the Stats side. To enable it, the macOS widgets option must be enabled in the Stats settings. More details you can find here.

Solution: open Stats Settings and toggle macOS widgets ON.

Stats tries to be efficient as it's possible. But reading some data periodically is not a cheap task. Each module has its own "price". So, if you want to reduce energy impact from the Stats you need to disable some Stats modules. The most inefficient modules are Sensors and Bluetooth. Disabling these modules could reduce CPU usage and power efficiency by up to 50% in some cases.

If you want to develop a new feature or you've found something that doesn't work, the first step is to open an issue so the feature or problem can be discussed. Pull requests should only be opened for existing issues and after discussion; otherwise, they may be closed automatically. There are a few cases where this can be skipped: for language changes, and for contributors who have already made significant contributions and whose implementations align well with the project.

Report issues or request features at: https://github.com/solbish/stats/issues

MIT License