Skip to content

README.md

Latest commit

 

History

History
152 lines (113 loc) · 4.2 KB

README.md

File metadata and controls

152 lines (113 loc) · 4.2 KB

Claude Usage Tracker

A macOS menu bar app that displays your Claude usage limits and reset times. Shows your 5-hour session usage, weekly limits, and extra usage spending in real-time.

Menu Bar Python

Features

  • Live usage percentage in menu bar (5-hour session)
  • 5-hour session usage with reset countdown
  • Weekly limits with reset date
  • Sonnet-specific weekly limit tracking
  • Extra usage spending ($X/$Y format)
  • Auto-refresh every 60 seconds
  • Secure - uses Claude Code's existing OAuth credentials from macOS Keychain

Screenshot

Claude Usage Tracker

Requirements

  • macOS
  • Python 3.9+
  • Claude Code installed and logged in
  • Claude Pro or Max subscription

Installation

Quick Install

cd ~/claude-usage-tracker
./install.sh

Manual Install

# Clone the repo
git clone https://github.com/cfranci/claude-usage-tracker.git
cd claude-usage-tracker

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Run
python tracker.py

Usage

  1. First, make sure you're logged into Claude Code (claude command works)
  2. Run the tracker: 
    cd ~/claude-usage-tracker
./venv/bin/python tracker.py
  3. Look for the percentage in your menu bar
  4. Click to see detailed usage breakdown

Auto-start at Login

The install script can set up auto-start, or manually create a Launch Agent:

mkdir -p ~/Library/LaunchAgents

cat > ~/Library/LaunchAgents/com.claude-usage-tracker.plist << EOF
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.claude-usage-tracker</string>
    <key>ProgramArguments</key>
    <array>
        <string>$HOME/claude-usage-tracker/venv/bin/python</string>
        <string>$HOME/claude-usage-tracker/tracker.py</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
</dict>
</plist>
EOF

How It Works

The app reads your Claude Code OAuth credentials from macOS Keychain (Claude Code-credentials) and queries the Anthropic usage API endpoint to get your current limits:

  • five_hour - Rolling 5-hour usage window
  • seven_day - Weekly usage cap
  • seven_day_sonnet - Sonnet-specific weekly limit
  • extra_usage - Overage spending if enabled

The usage API is free to call and doesn't consume any tokens.

Files

File Description
tracker.py Main menu bar app
anthropic_api.py API client for OAuth usage endpoint
config.py Keychain and config management
requirements.txt Python dependencies
install.sh Installation script

Troubleshooting

"?" in menu bar or usage shows 0%

  • Make sure Claude Code is installed and logged in
  • Run claude in terminal to verify it works
  • For Pro/Max users: Your OAuth token may have expired. Follow these steps:
    1. Open terminal and run: claude setup-token
    2. This opens a browser to re-authenticate with your Claude subscription
    3. After authenticating, restart the tracker
  • API key users: This app requires a Pro or Max subscription. API credits cannot be used to track subscription usage limits.

Getting "OAuth token has expired" error

The OAuth token in your Keychain has expired. To fix:

  1. Delete old credentials: security delete-generic-password -s "Claude Code-credentials"
  2. Run claude setup-token to get a fresh token
  3. Restart the tracker

Requirements

  • Claude Pro or Max subscription (not API credits)
  • Valid billing on your Anthropic account
  • OAuth tokens come from your subscription, not API keys

App doesn't start

  • Check Python version: python3 --version (needs 3.9+)
  • Reinstall dependencies: pip install -r requirements.txt

Usage shows 0%

  • Your session may have just reset
  • Try clicking "Refresh"

License

MIT

Credits

Built for tracking Claude usage limits on macOS.

Uses rumps for menu bar integration.