🎯 Claude Code Usage Monitor
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.
📑 Table of Contents
✨ Features
🔄 Real-time monitoring - Updates every 3 seconds with smooth refresh
- Updates every 3 seconds with smooth refresh 📊 Visual progress bars - Beautiful color-coded token and time progress bars
- Beautiful color-coded token and time progress bars 🔮 Smart predictions - Calculates when tokens will run out based on current burn rate
- Calculates when tokens will run out based on current burn rate 🤖 Auto-detection - Automatically switches to custom max when Pro limit is exceeded
- Automatically switches to custom max when Pro limit is exceeded 📋 Multiple plan support - Works with Pro, Max5, Max20, and auto-detect plans
- Works with Pro, Max5, Max20, and auto-detect plans ⚠️ Warning system - Alerts when tokens exceed limits or will deplete before session reset
- Alerts when tokens exceed limits or will deplete before session reset 💼 Professional UI - Clean, colorful terminal interface with emojis
- Clean, colorful terminal interface with emojis ✨ No screen flicker - Smooth updates without clearing the entire screen
- Smooth updates without clearing the entire screen ⏰ Customizable reset times - Set your own token reset schedule
🚀 Installation
Prerequisites
Python 3.6+ installed on your system pytz Python package: pip install pytz ccusage CLI tool installed globally: npm install -g ccusage
Quick Setup
# Clone the repository git clone https://github.com/Maciek-roboblog/Claude-Code-Usage-Monitor.git cd Claude-Code-Usage-Monitor # Make the script executable chmod +x ccusage_monitor.py # Run the monitor ./ccusage_monitor.py
📖 Usage
Basic Usage
Run with default settings (Pro plan - 7,000 tokens):
./ccusage_monitor.py
💡 Smart Detection: When tokens exceed the Pro limit, the monitor automatically switches to custom_max mode and displays a notification.
Specify Your Plan
# 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
Custom Reset Times
Set a custom daily reset hour (0-23):
# Reset at 3 AM ./ccusage_monitor.py --reset-hour 3 # Reset at 10 PM ./ccusage_monitor.py --reset-hour 22
Timezone Configuration
The default timezone is Europe/Warsaw. You can 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
Exit the Monitor
Press Ctrl+C to gracefully exit the monitoring tool.
📊 Understanding Claude Sessions
How Sessions Work
Claude Code operates on a 5-hour rolling session window system:
Sessions start with your first message to Claude
with your first message to Claude Sessions last for exactly 5 hours from that first message
for exactly 5 hours from that first message Token limits apply within each 5-hour session window
apply within each 5-hour session window Multiple sessions can be active simultaneously
Token Reset Schedule
Default reset times (in your configured timezone, default: Europe/Warsaw):
04:00 , 09:00 , 14:00 , 18:00 , 23:00
⚠️ Important: These are reference times. Your actual token refresh happens 5 hours after YOUR first message in each session.
🌍 Timezone Note: The default timezone is Europe/Warsaw. You can change it using the --timezone parameter with any valid timezone name.
Burn Rate Calculation
The monitor calculates burn rate based on all sessions from the last hour:
Analyzes token consumption across overlapping sessions
Provides accurate recent usage patterns
Updates predictions in real-time
🛠️ Token Limits by Plan
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 Automatically uses highest from previous sessions
🔧 Advanced Features
Auto-Detection Mode
When using --plan custom_max , the monitor:
🔍 Scans all previous session blocks 📈 Finds the highest token count used ⚙️ Sets that as your limit automatically ✅ Perfect for users with varying token limits
Smart Pro Plan Switching
When using the default Pro plan:
🔍 Monitor detects when usage exceeds 7,000 tokens
🔄 Automatically switches to custom_max mode
📢 Shows notification of the switch
▶️ Continues monitoring with the new limit
⚡ Best Practices
🚀 Start Early: Begin monitoring when you start a new session 👀 Watch Velocity: Monitor burn rate indicators to manage usage 📅 Plan Ahead: If tokens will deplete before reset, adjust your usage ⏰ Custom Schedule: Set --reset-hour to match your typical work schedule 🤖 Use Auto-Detect: Let the monitor figure out your limits with --plan custom_max
🐛 Troubleshooting
"Failed to get usage data"
Ensure ccusage is installed: npm install -g ccusage
is installed: Check if you have an active Claude session
Verify ccusage works: ccusage blocks --json
"No active session found"
Start a new Claude Code session
The monitor only works when there's an active session
Cursor remains hidden after exit
printf ' \033[?25h '
Display issues or overlapping text
Ensure your terminal window is at least 80 characters wide
Try resizing your terminal and restarting the monitor
🚀 Example Usage Scenarios
Morning Developer
# Start work at 9 AM daily ./ccusage_monitor.py --reset-hour 9
Night Owl Coder
# Often work past midnight ./ccusage_monitor.py --reset-hour 0
Heavy User with Variable Limits
# Let the monitor figure out your limits ./ccusage_monitor.py --plan custom_max
Quick Check with Default Settings
# Just run it! ./ccusage_monitor.py
International User
# Use your local timezone ./ccusage_monitor.py --timezone America/New_York ./ccusage_monitor.py --timezone Asia/Singapore ./ccusage_monitor.py --timezone Australia/Sydney
🤝 Contributing
Contributions are welcome! Feel free to:
🐛 Report bugs or issues
💡 Suggest new features
🔧 Submit pull requests
📚 Improve documentation
📊 Help Us Improve Token Limit Detection
We're collecting data about actual token limits to improve the auto-detection feature. If you're using Claude and your tokens exceeded the standard limits, please share your experience in Issue #1:
What to share:
Your subscription type (Pro, Teams, Enterprise)
The maximum tokens you reached (custom_max value)
When the limit was exceeded
Any patterns you've noticed
This data helps us better understand token allocation across different subscription tiers and improve the monitoring tool for everyone.
📝 License
MIT License - feel free to use and modify as needed.
🙏 Acknowledgments
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.
🏗️ Built for monitoring Claude Code token usage
🔧 Uses ccusage for data retrieval
💭 Inspired by the need for better token usage visibility