claude-usage-monitor

🎯 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

• ✨ Key Features
• 🚀 Installation
  • ⚡ Quick Start
  • 🔒 Production Setup (Recommended)
  • Virtual Environment Setup
• 📖 Usage
  • Basic Usage
  • Configuration Options
  • Available Plans
• ✨ Features & How It Works
  • Current Features
  • Understanding Claude Sessions
  • Token Limits by Plan
  • Smart Detection Features
• 🚀 Usage Examples
  • Common Scenarios
  • Best Practices
• Troubleshooting
  • No active session found
• 📞 Contact
• 📚 Additional Documentation
• 📝 License
• 🤝 Contributors
• 🙏 Acknowledgments

✨ Key Features

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

🚀 Installation

⚡ Modern Installation with uv (Recommended)

The fastest and easiest way to install and use the monitor:

First-time uv users

If you don't have uv installed yet, get it with one command:

# Install uv (one-time setup)

# On Linux/macOS:
curl -LsSf https://astral.sh/uv/install.sh | sh

# On Windows:
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# After installation, restart your terminal

Install and run the monitor

# Install dependencies
npm install -g ccusage

# Clone and install the tool with uv
git clone https://github.com/Maciek-roboblog/Claude-Code-Usage-Monitor.git
cd Claude-Code-Usage-Monitor
uv tool install .

# Run from anywhere
ccusage-monitor
# or
claude-monitor

🔧 Legacy Installation Methods

Quick Start (Development/Testing)

For immediate testing or development:

# 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 claude_monitor.py

Prerequisites

• Python 3.7+ installed on your system
• Node.js for ccusage CLI tool

Virtual Environment Setup

Why Use Virtual Environment?

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

Installing virtualenv (if needed)

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 installation

Alternatively, use the virtualenv package:

# Install virtualenv via pip
pip install virtualenv

# Then create virtual environment with:
virtualenv venv
# instead of: python3 -m venv venv

Step-by-Step Setup

# 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 claude_monitor.py

# 7. Run the monitor
python claude_monitor.py

Daily Usage

After 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
./claude_monitor.py  # Linux/Mac
# python claude_monitor.py  # Windows

# When done, deactivate
deactivate

Pro Tip: Shell Alias

Create an alias for quick access:

# Add to ~/.bashrc or ~/.zshrc
alias claude-monitor='cd ~/Claude-Code-Usage-Monitor && source venv/bin/activate && ./claude_monitor.py'

# Then just run:
claude-monitor

📖 Usage

Basic Usage

With uv tool installation (Recommended)

# Default (Pro plan - 7,000 tokens)
claude-monitor

# Exit the monitor
# Press Ctrl+C to gracefully exit

Traditional/Development mode

# Default (Pro plan - 7,000 tokens)
./claude_monitor.py

# Exit the monitor
# Press Ctrl+C to gracefully exit

Configuration Options

Specify Your Plan

With uv tool installation:

# Pro plan (~7,000 tokens) - Default
claude-monitor --plan pro

# Max5 plan (~35,000 tokens)
claude-monitor --plan max5

# Max20 plan (~140,000 tokens)
claude-monitor --plan max20

# Auto-detect from highest previous session
claude-monitor --plan custom_max

Traditional/Development mode:

# Pro plan (~7,000 tokens) - Default
./claude_monitor.py --plan pro

# Max5 plan (~35,000 tokens)
./claude_monitor.py --plan max5

# Max20 plan (~140,000 tokens)
./claude_monitor.py --plan max20

# Auto-detect from highest previous session
./claude_monitor.py --plan custom_max

Custom Reset Times

With uv tool installation:

# Reset at 3 AM
claude-monitor --reset-hour 3

# Reset at 10 PM
claude-monitor --reset-hour 22

Traditional/Development mode:

# Reset at 3 AM
./claude_monitor.py --reset-hour 3

# Reset at 10 PM
./claude_monitor.py --reset-hour 22

Timezone Configuration

The default timezone is Europe/Warsaw. Change it to any valid timezone:

With uv tool installation:

# Use US Eastern Time
claude-monitor --timezone US/Eastern

# Use Tokyo time
claude-monitor --timezone Asia/Tokyo

# Use UTC
claude-monitor --timezone UTC

# Use London time
claude-monitor --timezone Europe/London

Traditional/Development mode:

# Use US Eastern Time
./claude_monitor.py --timezone US/Eastern

# Use Tokyo time
./claude_monitor.py --timezone Asia/Tokyo

# Use UTC
./claude_monitor.py --timezone UTC

# Use London time
./claude_monitor.py --timezone Europe/London

Available Plans

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

✨ Features & How It Works

Current Features

🔄 Real-time Monitoring

• Updates every 3 seconds with smooth refresh
• No screen flicker - intelligent display updates
• Live token consumption tracking across multiple sessions

📊 Visual Progress Bars

• 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

🔮 Smart Predictions

• 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

🤖 Auto-Detection System

• 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

Understanding Claude Sessions

How Claude Code Sessions Work

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

Session Reset Schedule

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)

Burn Rate Calculation

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

Token Limits by Plan

Standard Plans

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

Auto-Detection Plans

Plan	How It Works	Best For
custom_max	Scans all previous sessions, uses highest token count found	Users with variable/unknown limits

Smart Detection Features

Automatic Plan Switching

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

Limit Discovery Process

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

🚀 Usage Examples

Common Scenarios

🌅 Morning Developer

Scenario: You start work at 9 AM and want tokens to reset aligned with your schedule.

# Set custom reset time to 9 AM
./claude_monitor.py --reset-hour 9

# With your timezone
./claude_monitor.py --reset-hour 9 --timezone US/Eastern

Benefits:

• Reset times align with your work schedule
• Better planning for daily token allocation
• Predictable session windows

🌙 Night Owl Coder

Scenario: You often work past midnight and need flexible reset scheduling.

# Reset at midnight for clean daily boundaries
./claude_monitor.py --reset-hour 0

# Late evening reset (11 PM)
./claude_monitor.py --reset-hour 23

Strategy:

• Plan heavy coding sessions around reset times
• Use late resets to span midnight work sessions
• Monitor burn rate during peak hours

🔄 Heavy User with Variable Limits

Scenario: Your token limits seem to change, and you're not sure of your exact plan.

# Auto-detect your highest previous usage
claude-monitor --plan custom_max

# Monitor with custom scheduling
claude-monitor --plan custom_max --reset-hour 6

Approach:

• Let auto-detection find your real limits
• Monitor for a week to understand patterns
• Note when limits change or reset

🌍 International User

Scenario: You're working across different timezones or traveling.

# US East Coast
claude-monitor --timezone America/New_York

# Europe
claude-monitor --timezone Europe/London

# Asia Pacific
claude-monitor --timezone Asia/Singapore

# UTC for international team coordination
claude-monitor --timezone UTC --reset-hour 12

⚡ Quick Check

Scenario: You just want to see current status without configuration.

# Just run it with defaults
ccusage-monitor

# Press Ctrl+C after checking status

Plan Selection Strategies

How to Choose Your Plan

Start with Default (Recommended for New Users)

# Pro plan detection with auto-switching
ccusage-monitor

• 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
claude-monitor --plan max5

# If you know you have Max20
claude-monitor --plan max20

Unknown Limits

# Auto-detect from previous usage
claude-monitor --plan custom_max

Best Practices

Setup Best Practices

• Start Early in Sessions

  # Begin monitoring when starting Claude work (uv installation)
  ccusage-monitor
  
  # Or development mode
  ./claude_monitor.py
  

  • Gives accurate session tracking from the start
  • Better burn rate calculations
  • Early warning for limit approaches

• Use Modern Installation (Recommended)

  # Easy installation and updates with uv
  uv tool install claude-usage-monitor
  claude-monitor --plan max5
  

  • Clean system installation
  • Easy updates and maintenance
  • Available from anywhere

• Custom Shell Alias (Legacy Setup)

  # Add to ~/.bashrc or ~/.zshrc (only for development setup)
  alias claude-monitor='cd ~/Claude-Code-Usage-Monitor && source venv/bin/activate && ./claude_monitor.py'
  

Usage Best Practices

• 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
  claude-monitor --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
  claude-monitor --timezone Europe/Warsaw
  

  • Accurate reset time predictions
  • Better planning for work schedules
  • Correct session expiration estimates

Optimization Tips

• 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 (uv installation)
  tmux new-session -d -s claude-monitor 'ccusage-monitor'
  
  # Or development mode
  tmux new-session -d -s claude-monitor './claude_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

Real-World Workflows

Large Project Development

# Setup for sustained development
claude-monitor --plan max20 --reset-hour 8 --timezone America/New_York

Daily 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
claude-monitor --plan pro

Sprint Development

# High-intensity development setup
claude-monitor --plan max20 --reset-hour 6

Troubleshooting

No active session found

If 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 ./claude_monitor.py

📞 Contact

Have questions, suggestions, or want to collaborate? Feel free to reach out!

📧 Email: [e-mail]

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!

📚 Additional Documentation

• Development Roadmap - ML features, PyPI package, Docker plans
• Contributing Guide - How to contribute, development guidelines
• Troubleshooting - Common issues and solutions

📝 License

MIT License - feel free to use and modify as needed.

🤝 Contributors

• @adawalli
• @taylorwilsdon
• @moneroexamples

Want to contribute? Check out our Contributing Guide!

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

Star History

⭐ Star this repo if you find it useful! ⭐

Report Bug • Request Feature • Contribute