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.
- 🔄 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
- ✨ No screen flicker - Smooth updates without clearing the entire screen
- ⏰ Customizable reset times - Set your own token reset schedule
- Python 3.6+ installed on your system
- pytz Python package:
- ccusage CLI tool installed globally:
# 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.pyRun with default settings (Pro plan - 7,000 tokens):
💡 Smart Detection: When tokens exceed the Pro limit, the monitor automatically switches to custom_max mode and displays a notification.
# 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_maxSet 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 22The 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/LondonPress Ctrl+C to gracefully exit the monitoring tool.
Claude Code operates on a 5-hour rolling session window system:
- Sessions start with your first message to Claude
- Sessions last for exactly 5 hours from that first message
- Token limits apply within each 5-hour session window
- Multiple sessions can be active simultaneously
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
--timezoneparameter with any valid timezone name.
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
| 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 |
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
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
- 🚀 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-hourto match your typical work schedule - 🤖 Use Auto-Detect: Let the monitor figure out your limits with
--plan custom_max
- Ensure
ccusageis installed:npm install -g ccusage - Check if you have an active Claude session
- Verify
ccusageworks:ccusage blocks --json
- Start a new Claude Code session
- The monitor only works when there's an active session
Cursor remains hidden after exit
- Ensure your terminal window is at least 80 characters wide
- Try resizing your terminal and restarting the monitor
# Start work at 9 AM daily
./ccusage_monitor.py --reset-hour 9# Often work past midnight
./ccusage_monitor.py --reset-hour 0# Let the monitor figure out your limits
./ccusage_monitor.py --plan custom_max# Just run it!
./ccusage_monitor.py# Use your local timezone
./ccusage_monitor.py --timezone America/New_York
./ccusage_monitor.py --timezone Asia/Singapore
./ccusage_monitor.py --timezone Australia/SydneyContributions are welcome! Feel free to:
- 🐛 Report bugs or issues
- 💡 Suggest new features
- 🔧 Submit pull requests
- 📚 Improve documentation
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.
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.
- 🏗️ Built for monitoring Claude Code token usage
- 🔧 Uses ccusage for data retrieval
- 💭 Inspired by the need for better token usage visibility