Show HN: Claude Code Usage Monitor – real-time tracker to dodge usage cut-offs

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.

• ✨ Features
• 🚀 Installation
  • Prerequisites
  • Quick Setup
• 📖 Usage
  • Basic Usage
  • Specify Your Plan
  • Custom Reset Times
  • Timezone Configuration
  • Exit the Monitor
• 📊 Understanding Claude Sessions
  • How Sessions Work
  • Token Reset Schedule
  • Burn Rate Calculation
• 🛠️ Token Limits by Plan
• 🔧 Advanced Features
  • Auto-Detection Mode
  • Smart Pro Plan Switching
• ⚡ Best Practices
• 🐛 Troubleshooting
• 🚀 Example Usage Scenarios
• 🤝 Contributing
• 📝 License
• 🙏 Acknowledgments

• 🔄 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

1. Python 3.6+ installed on your system
2. pytz Python package:
3. ccusage CLI tool installed globally:

Run 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.

Set a custom daily reset hour (0-23):

The default timezone is Europe/Warsaw. You can change it to any valid timezone:

Press 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 --timezone parameter 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

When using --plan custom_max, the monitor:

1. 🔍 Scans all previous session blocks
2. 📈 Finds the highest token count used
3. ⚙️ Sets that as your limit automatically
4. ✅ 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

1. 🚀 Start Early: Begin monitoring when you start a new session
2. 👀 Watch Velocity: Monitor burn rate indicators to manage usage
3. 📅 Plan Ahead: If tokens will deplete before reset, adjust your usage
4. ⏰ Custom Schedule: Set --reset-hour to match your typical work schedule
5. 🤖 Use Auto-Detect: Let the monitor figure out your limits with --plan custom_max

• Ensure ccusage is installed: npm install -g ccusage
• Check if you have an active Claude session
• Verify ccusage works: ccusage blocks --json

• Start a new Claude Code session
• The monitor only works when there's an active session

• Ensure your terminal window is at least 80 characters wide
• Try resizing your terminal and restarting the monitor

Contributions 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