A beautiful real-time terminal monitoring tool for Claude AI token usage. Track your token consumption, burn rate, and get predictions about when you'll run out of tokens.
- ✨ Key Features
- 🚀 Installation
- 📖 Usage
- ✨ Features & How It Works
- 🚀 Usage Examples
- Troubleshooting
- 📞 Contact
- 📚 Additional Documentation
- 🔄 Real-time monitoring - Updates every 3 seconds with smooth refresh
- 📊 Visual progress bars - Beautiful color-coded token and time progress bars
- 🔮 Smart predictions - Calculates when tokens will run out based on current burn rate
- 🤖 Auto-detection - Automatically switches to custom max when Pro limit is exceeded
- 📋 Multiple plan support - Works with Pro, Max5, Max20, and auto-detect plans
⚠️ Warning system - Alerts when tokens exceed limits or will deplete before session reset- 💼 Professional UI - Clean, colorful terminal interface with emojis
- ⏰ Customizable scheduling - Set your own reset times and timezones
For immediate testing (not recommended for regular use):
# Install dependencies
npm install -g ccusage
pip install pytz
# Clone and run
git clone https://github.com/Maciek-roboblog/Claude-Code-Usage-Monitor.git
cd Claude-Code-Usage-Monitor
python ccusage_monitor.py- Python 3.6+ installed on your system
- Node.js for ccusage CLI tool
Using a virtual environment is strongly recommended because:
- 🛡️ Isolation: Keeps your system Python clean and prevents dependency conflicts
- 📦 Portability: Easy to replicate the exact environment on different machines
- 🔄 Version Control: Lock specific versions of dependencies for stability
- 🧹 Clean Uninstall: Simply delete the virtual environment folder to remove everything
- 👥 Team Collaboration: Everyone uses the same Python and package versions
If you don't have venv module available:
# Ubuntu/Debian
sudo apt-get update
sudo apt-get install python3-venv
# Fedora/RHEL/CentOS
sudo dnf install python3-venv
# macOS (usually comes with Python)
# If not available, install Python via Homebrew:
brew install python3
# Windows (usually comes with Python)
# If not available, reinstall Python from python.org
# Make sure to check "Add Python to PATH" during installationAlternatively, use the virtualenv package:
# Install virtualenv via pip
pip install virtualenv
# Then create virtual environment with:
virtualenv venv
# instead of: python3 -m venv venv# 1. Install ccusage globally
npm install -g ccusage
# 2. Clone the repository
git clone https://github.com/Maciek-roboblog/Claude-Code-Usage-Monitor.git
cd Claude-Code-Usage-Monitor
# 3. Create virtual environment
python3 -m venv venv
# Or if using virtualenv package:
# virtualenv venv
# 4. Activate virtual environment
# On Linux/Mac:
source venv/bin/activate
# On Windows:
# venv\Scripts\activate
# 5. Install Python dependencies
pip install pytz
# 6. Make script executable (Linux/Mac only)
chmod +x ccusage_monitor.py
# 7. Run the monitor
python ccusage_monitor.pyAfter initial setup, you only need:
# Navigate to project directory
cd Claude-Code-Usage-Monitor
# Activate virtual environment
source venv/bin/activate # Linux/Mac
# venv\Scripts\activate # Windows
# Run monitor
./ccusage_monitor.py # Linux/Mac
# python ccusage_monitor.py # Windows
# When done, deactivate
deactivateCreate an alias for quick access:
# Add to ~/.bashrc or ~/.zshrc
alias claude-monitor='cd ~/Claude-Code-Usage-Monitor && source venv/bin/activate && ./ccusage_monitor.py'
# Then just run:
claude-monitor# Default (Pro plan - 7,000 tokens)
./ccusage_monitor.py
# Exit the monitor
# Press Ctrl+C to gracefully exit# Pro plan (~7,000 tokens) - Default
./ccusage_monitor.py --plan pro
# Max5 plan (~35,000 tokens)
./ccusage_monitor.py --plan max5
# Max20 plan (~140,000 tokens)
./ccusage_monitor.py --plan max20
# Auto-detect from highest previous session
./ccusage_monitor.py --plan custom_max# Reset at 3 AM
./ccusage_monitor.py --reset-hour 3
# Reset at 10 PM
./ccusage_monitor.py --reset-hour 22The default timezone is Europe/Warsaw. Change it to any valid timezone:
# Use US Eastern Time
./ccusage_monitor.py --timezone US/Eastern
# Use Tokyo time
./ccusage_monitor.py --timezone Asia/Tokyo
# Use UTC
./ccusage_monitor.py --timezone UTC
# Use London time
./ccusage_monitor.py --timezone Europe/London| Plan | Token Limit | Best For |
|---|---|---|
| pro | ~7,000 | Light usage, testing (default) |
| max5 | ~35,000 | Regular development |
| max20 | ~140,000 | Heavy usage, large projects |
| custom_max | Auto-detect | Uses highest from previous sessions |
- Updates every 3 seconds with smooth refresh
- No screen flicker - intelligent display updates
- Live token consumption tracking across multiple sessions
- Token Progress: Color-coded bars showing current usage vs limits
- Time Progress: Visual countdown to next session reset
- Burn Rate Indicator: Real-time consumption velocity
- Calculates when tokens will run out based on current burn rate
- Warns if tokens will deplete before next session reset
- Analyzes usage patterns from the last hour
- Smart Plan Switching: Automatically switches from Pro to custom_max when limits exceeded
- Limit Discovery: Scans previous sessions to find your actual token limits
- Intelligent Notifications: Shows when automatic switches occur
Claude Code operates on a 5-hour rolling session window system:
- Session Start: Begins with your first message to Claude
- Session Duration: Lasts exactly 5 hours from that first message
- Token Limits: Apply within each 5-hour session window
- Multiple Sessions: Can have several active sessions simultaneously
- Rolling Windows: New sessions can start while others are still active
Default reference times (in your configured timezone):
04:00,09:00,14:00,18:00,23:00
⚠️ Important: These are reference times for planning. Your actual token refresh happens exactly 5 hours after YOUR first message in each session.
Example Session Timeline:
10:30 AM - First message (Session A starts)
03:30 PM - Session A expires (5 hours later)
12:15 PM - First message (Session B starts)
05:15 PM - Session B expires (5 hours later)
The monitor calculates burn rate using sophisticated analysis:
- Data Collection: Gathers token usage from all sessions in the last hour
- Pattern Analysis: Identifies consumption trends across overlapping sessions
- Velocity Tracking: Calculates tokens consumed per minute
- Prediction Engine: Estimates when current session tokens will deplete
- Real-time Updates: Adjusts predictions as usage patterns change
| Plan | Approximate Limit | Typical Usage |
|---|---|---|
| Claude Pro | ~7,000 tokens | Light coding, testing, learning |
| Claude Max5 | ~35,000 tokens | Regular development work |
| Claude Max20 | ~140,000 tokens | Heavy usage, large projects |
| Plan | How It Works | Best For |
|---|---|---|
| custom_max | Scans all previous sessions, uses highest token count found | Users with variable/unknown limits |
When using the default Pro plan:
- Detection: Monitor notices token usage exceeding 7,000
- Analysis: Scans previous sessions for actual limits
- Switch: Automatically changes to custom_max mode
- Notification: Displays clear message about the change
- Continuation: Keeps monitoring with new, higher limit
The auto-detection system:
- Scans History: Examines all available session blocks
- Finds Peaks: Identifies highest token usage achieved
- Validates Data: Ensures data quality and recency
- Sets Limits: Uses discovered maximum as new limit
- Learns Patterns: Adapts to your actual usage capabilities
Scenario: You start work at 9 AM and want tokens to reset aligned with your schedule.
# Set custom reset time to 9 AM
./ccusage_monitor.py --reset-hour 9
# With your timezone
./ccusage_monitor.py --reset-hour 9 --timezone US/EasternBenefits:
- Reset times align with your work schedule
- Better planning for daily token allocation
- Predictable session windows
Scenario: You often work past midnight and need flexible reset scheduling.
# Reset at midnight for clean daily boundaries
./ccusage_monitor.py --reset-hour 0
# Late evening reset (11 PM)
./ccusage_monitor.py --reset-hour 23Strategy:
- Plan heavy coding sessions around reset times
- Use late resets to span midnight work sessions
- Monitor burn rate during peak hours
Scenario: Your token limits seem to change, and you're not sure of your exact plan.
# Auto-detect your highest previous usage
./ccusage_monitor.py --plan custom_max
# Monitor with custom scheduling
./ccusage_monitor.py --plan custom_max --reset-hour 6Approach:
- Let auto-detection find your real limits
- Monitor for a week to understand patterns
- Note when limits change or reset
Scenario: You're working across different timezones or traveling.
# US East Coast
./ccusage_monitor.py --timezone America/New_York
# Europe
./ccusage_monitor.py --timezone Europe/London
# Asia Pacific
./ccusage_monitor.py --timezone Asia/Singapore
# UTC for international team coordination
./ccusage_monitor.py --timezone UTC --reset-hour 12Scenario: You just want to see current status without configuration.
# Just run it with defaults
./ccusage_monitor.py
# Press Ctrl+C after checking statusStart with Default (Recommended for New Users)
# Pro plan detection with auto-switching
./ccusage_monitor.py- Monitor will detect if you exceed Pro limits
- Automatically switches to custom_max if needed
- Shows notification when switching occurs
Known Subscription Users
# If you know you have Max5
./ccusage_monitor.py --plan max5
# If you know you have Max20
./ccusage_monitor.py --plan max20Unknown Limits
# Auto-detect from previous usage
./ccusage_monitor.py --plan custom_max-
Start Early in Sessions
# Begin monitoring when starting Claude work ./ccusage_monitor.py- Gives accurate session tracking from the start
- Better burn rate calculations
- Early warning for limit approaches
-
Use Virtual Environment
# Production setup with isolation python3 -m venv venv source venv/bin/activate pip install pytz
- Prevents dependency conflicts
- Clean uninstallation
- Reproducible environments
-
Custom Shell Alias
# Add to ~/.bashrc or ~/.zshrc alias claude-monitor='cd ~/Claude-Code-Usage-Monitor && source venv/bin/activate && ./ccusage_monitor.py'
-
Monitor Burn Rate Velocity
- Watch for sudden spikes in token consumption
- Adjust coding intensity based on remaining time
- Plan big refactors around session resets
-
Strategic Session Planning
# Plan heavy usage around reset times ./ccusage_monitor.py --reset-hour 9- Schedule large tasks after resets
- Use lighter tasks when approaching limits
- Leverage multiple overlapping sessions
-
Timezone Awareness
# Always use your actual timezone ./ccusage_monitor.py --timezone Europe/Warsaw- Accurate reset time predictions
- Better planning for work schedules
- Correct session expiration estimates
-
Terminal Setup
- Use terminals with at least 80 character width
- Enable color support for better visual feedback
- Consider dedicated terminal window for monitoring
-
Workflow Integration
# Start monitoring with your development session tmux new-session -d -s claude-monitor './ccusage_monitor.py' # Check status anytime tmux attach -t claude-monitor
-
Multi-Session Strategy
- Remember sessions last exactly 5 hours
- You can have multiple overlapping sessions
- Plan work across session boundaries
Large Project Development
# Setup for sustained development
./ccusage_monitor.py --plan max20 --reset-hour 8 --timezone America/New_YorkDaily Routine:
- 8:00 AM: Fresh tokens, start major features
- 10:00 AM: Check burn rate, adjust intensity
- 12:00 PM: Monitor for afternoon session planning
- 2:00 PM: New session window, tackle complex problems
- 4:00 PM: Light tasks, prepare for evening session
Learning & Experimentation
# Flexible setup for learning
./ccusage_monitor.py --plan proSprint Development
# High-intensity development setup
./ccusage_monitor.py --plan max20 --reset-hour 6If you encounter the error No active session found, please follow these steps:
-
Initial Test: Launch Claude Code and send at least two messages. In some cases, the session may not initialize correctly on the first attempt, but it resolves after a few interactions.
-
Configuration Path: If the issue persists, consider specifying a custom configuration path. By default, Claude Code uses
~/.config/claude. You may need to adjust this path depending on your environment.
CLAUDE_CONFIG_DIR=~/.config/claude ./ccusage_monitor.pyHave questions, suggestions, or want to collaborate? Feel free to reach out!
📧 Email: maciek@roboblog.eu
Whether you need help with setup, have feature requests, found a bug, or want to discuss potential improvements, don't hesitate to get in touch. I'm always happy to help and hear from users of the Claude Code Usage Monitor!
- Development Roadmap - ML features, PyPI package, Docker plans
- Contributing Guide - How to contribute, development guidelines
- Troubleshooting - Common issues and solutions
MIT License - feel free to use and modify as needed.
This tool builds upon the excellent ccusage by @ryoppippi, adding a real-time monitoring interface with visual progress bars, burn rate calculations, and predictive analytics.
⭐ Star this repo if you find it useful! ⭐