ccusage-monitor 0.0.2

Real-time Claude token usage monitor with beautiful terminal interface

🎯 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

---

✨ 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

⚡ Quick Start

Option 1: Using uvx (Simplest)

If you have uv installed, you can run the monitor directly:

# First, install ccusage globally (one-time setup)
npm install -g ccusage

# Then run directly from GitHub
uvx --from git+https://github.com/Maciek-roboblog/Claude-Code-Usage-Monitor.git ccusage-monitor

# Or clone and run locally
git clone https://github.com/Maciek-roboblog/Claude-Code-Usage-Monitor.git
cd Claude-Code-Usage-Monitor
uvx --from . ccusage-monitor

Option 2: Traditional Installation

# Install Node.js dependency
npm install -g ccusage

# Clone the repository
git clone https://github.com/Maciek-roboblog/Claude-Code-Usage-Monitor.git
cd Claude-Code-Usage-Monitor

# Install Python dependencies
pip install -r requirements.txt

# Run the monitor
python ccusage_monitor.py

🔒 Production Setup (Recommended)

Prerequisites

1. Python 3.6+ installed on your system
2. 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 -r requirements.txt

# 6. Make script executable (Linux/Mac only)
chmod +x ccusage_monitor.py

# 7. Run the monitor
python ccusage_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
./ccusage_monitor.py  # Linux/Mac
# python ccusage_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 && ./ccusage_monitor.py'

# Then just run:
claude-monitor

---

📖 Usage

Basic Usage

# Using uvx (no installation required)
uvx --from git+https://github.com/Maciek-roboblog/Claude-Code-Usage-Monitor.git ccusage-monitor

# Or if cloned locally with uvx
uvx --from . ccusage-monitor

# Traditional method (Pro plan - 7,000 tokens)
./ccusage_monitor.py

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

Configuration Options

Specify Your Plan

# Using uvx
uvx --from . ccusage-monitor --plan pro      # Pro plan (~7,000 tokens) - Default
uvx --from . ccusage-monitor --plan max5     # Max5 plan (~35,000 tokens)
uvx --from . ccusage-monitor --plan max20    # Max20 plan (~140,000 tokens)
uvx --from . ccusage-monitor --plan custom_max # Auto-detect from highest previous session

# Traditional method
./ccusage_monitor.py --plan pro              # Pro plan (~7,000 tokens) - Default
./ccusage_monitor.py --plan max5             # Max5 plan (~35,000 tokens)
./ccusage_monitor.py --plan max20            # Max20 plan (~140,000 tokens)
./ccusage_monitor.py --plan custom_max        # Auto-detect from highest previous session

Custom Reset Times

# Using uvx
uvx --from . ccusage-monitor --reset-hour 3   # Reset at 3 AM
uvx --from . ccusage-monitor --reset-hour 22  # Reset at 10 PM

# Traditional method
./ccusage_monitor.py --reset-hour 3           # Reset at 3 AM
./ccusage_monitor.py --reset-hour 22          # Reset at 10 PM

Timezone Configuration

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

# Using uvx
uvx --from . ccusage-monitor --timezone US/Eastern    # Use US Eastern Time
uvx --from . ccusage-monitor --timezone Asia/Tokyo    # Use Tokyo time
uvx --from . ccusage-monitor --timezone UTC           # Use UTC
uvx --from . ccusage-monitor --timezone Europe/London # Use London time

# Traditional method
./ccusage_monitor.py --timezone US/Eastern    # Use US Eastern Time
./ccusage_monitor.py --timezone Asia/Tokyo    # Use Tokyo time
./ccusage_monitor.py --timezone UTC           # Use UTC
./ccusage_monitor.py --timezone Europe/London # Use London time

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:

1. Session Start: Begins with your first message to Claude
2. Session Duration: Lasts exactly 5 hours from that first message
3. Token Limits: Apply within each 5-hour session window
4. Multiple Sessions: Can have several active sessions simultaneously
5. 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:

1. Data Collection: Gathers token usage from all sessions in the last hour
2. Pattern Analysis: Identifies consumption trends across overlapping sessions
3. Velocity Tracking: Calculates tokens consumed per minute
4. Prediction Engine: Estimates when current session tokens will deplete
5. 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:

1. Detection: Monitor notices token usage exceeding 7,000
2. Analysis: Scans previous sessions for actual limits
3. Switch: Automatically changes to custom_max mode
4. Notification: Displays clear message about the change
5. Continuation: Keeps monitoring with new, higher limit

Limit Discovery Process

The auto-detection system:

1. Scans History: Examines all available session blocks
2. Finds Peaks: Identifies highest token usage achieved
3. Validates Data: Ensures data quality and recency
4. Sets Limits: Uses discovered maximum as new limit
5. 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.

# Using uvx
uvx --from . ccusage-monitor --reset-hour 9
uvx --from . ccusage-monitor --reset-hour 9 --timezone US/Eastern

# Traditional method
./ccusage_monitor.py --reset-hour 9
./ccusage_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.

# Using uvx
uvx --from . ccusage-monitor --reset-hour 0   # Reset at midnight
uvx --from . ccusage-monitor --reset-hour 23  # Late evening reset (11 PM)

# Traditional method
./ccusage_monitor.py --reset-hour 0   # Reset at midnight
./ccusage_monitor.py --reset-hour 23  # Late evening reset (11 PM)

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.

# Using uvx
uvx --from . ccusage-monitor --plan custom_max
uvx --from . ccusage-monitor --plan custom_max --reset-hour 6

# Traditional method
./ccusage_monitor.py --plan custom_max
./ccusage_monitor.py --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.

# Using uvx
uvx --from . ccusage-monitor --timezone America/New_York  # US East Coast
uvx --from . ccusage-monitor --timezone Europe/London     # Europe
uvx --from . ccusage-monitor --timezone Asia/Singapore    # Asia Pacific
uvx --from . ccusage-monitor --timezone UTC --reset-hour 12  # UTC coordination

# Traditional method
./ccusage_monitor.py --timezone America/New_York  # US East Coast
./ccusage_monitor.py --timezone Europe/London     # Europe
./ccusage_monitor.py --timezone Asia/Singapore    # Asia Pacific
./ccusage_monitor.py --timezone UTC --reset-hour 12  # UTC coordination

⚡ Quick Check

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

# Using uvx (no installation needed!)
uvx --from git+https://github.com/Maciek-roboblog/Claude-Code-Usage-Monitor.git ccusage-monitor

# Traditional method
./ccusage_monitor.py

# 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.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 max20

Unknown Limits

# Auto-detect from previous usage
./ccusage_monitor.py --plan custom_max

Best Practices

Setup Best Practices

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

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

3. Custom Shell Alias

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

Usage Best Practices

1. Monitor Burn Rate Velocity

   • Watch for sudden spikes in token consumption
   • Adjust coding intensity based on remaining time
   • Plan big refactors around session resets

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

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

Optimization Tips

1. Terminal Setup

   • Use terminals with at least 80 character width
   • Enable color support for better visual feedback
   • Consider dedicated terminal window for monitoring

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

3. 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
./ccusage_monitor.py --plan max20 --reset-hour 8 --timezone America/New_York

Daily Routine:

1. 8:00 AM: Fresh tokens, start major features
2. 10:00 AM: Check burn rate, adjust intensity
3. 12:00 PM: Monitor for afternoon session planning
4. 2:00 PM: New session window, tackle complex problems
5. 4:00 PM: Light tasks, prepare for evening session

Learning & Experimentation

# Flexible setup for learning
./ccusage_monitor.py --plan pro

Sprint Development

# High-intensity development setup
./ccusage_monitor.py --plan max20 --reset-hour 6

Troubleshooting

No active session found

If you encounter the error No active session found, please follow these steps:

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

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

• Future Roadmap - Potential future features and enhancements
• Contributing Guide - How to contribute, development guidelines
• Troubleshooting - Common issues and solutions

---

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

---

⭐ Star this repo if you find it useful! ⭐

Report Bug • Request Feature • Contribute