# 🎯 Claude Code Usage Monitor
[](https://pypi.org/project/claude-monitor/)
[](https://python.org)
[](https://opensource.org/licenses/MIT)
[](http://makeapullrequest.com)
[](https://codecov.io/gh/Maciek-roboblog/Claude-Code-Usage-Monitor)
A beautiful real-time terminal monitoring tool for Claude AI token usage with advanced analytics, machine learning-based predictions, and Rich UI. Track your token consumption, burn rate, cost analysis, and get intelligent predictions about session limits.
---
## 📑 Table of Contents
- [✨ Key Features](#-key-features)
- [🚀 Installation](#-installation)
- [⚡ Modern Installation with uv (Recommended)](#-modern-installation-with-uv-recommended)
- [📦 Installation with pip](#-installation-with-pip)
- [🛠️ Other Package Managers](#️-other-package-managers)
- [📖 Usage](#-usage)
- [Get Help](#get-help)
- [Basic Usage](#basic-usage)
- [Configuration Options](#configuration-options)
- [Available Plans](#available-plans)
- [🙏 Please Help Test This Release!](#-please-help-test-this-release)
- [✨ Features & How It Works](#-features--how-it-works)
- [Current Features](#current-features)
- [Understanding Claude Sessions](#understanding-claude-sessions)
- [Token Limits by Plan](#token-limits-by-plan)
- [Smart Detection Features](#smart-detection-features)
- [🚀 Usage Examples](#-usage-examples)
- [Common Scenarios](#common-scenarios)
- [Best Practices](#best-practices)
- [🔧 Development Installation](#-development-installation)
- [Troubleshooting](#troubleshooting)
- [Installation Issues](#installation-issues)
- [Runtime Issues](#runtime-issues)
- [📞 Contact](#-contact)
- [📚 Additional Documentation](#-additional-documentation)
- [📝 License](#-license)
- [🤝 Contributors](#-contributors)
- [🙏 Acknowledgments](#-acknowledgments)
## ✨ Key Features
### 🚀 **v3.0.0 Major Update - Complete Architecture Rewrite**
- **🔮 ML-based predictions** - P90 percentile calculations and intelligent session limit detection
- **🔄 Real-time monitoring** - Configurable refresh rates (0.1-20 Hz) with intelligent display updates
- **📊 Advanced Rich UI** - Beautiful color-coded progress bars, tables, and layouts with WCAG-compliant contrast
- **🤖 Smart auto-detection** - Automatic plan switching with custom limit discovery
- **📋 Enhanced plan support** - Updated limits: Pro (44k), Max5 (88k), Max20 (220k), Custom (P90-based)
- **⚠️ Advanced warning system** - Multi-level alerts with cost and time predictions
- **💼 Professional Architecture** - Modular design with Single Responsibility Principle (SRP) compliance
- **🎨 Intelligent theming** - Scientific color schemes with automatic terminal background detection
- **⏰ Advanced scheduling** - Auto-detected system timezone and time format preferences
- **📈 Cost analytics** - Model-specific pricing with cache token calculations
- **🔧 Pydantic validation** - Type-safe configuration with automatic validation
- **📝 Comprehensive logging** - Optional file logging with configurable levels
- **🧪 Extensive testing** - 100+ test cases with full coverage
- **🎯 Error reporting** - Optional Sentry integration for production monitoring
- **⚡ Performance optimized** - Advanced caching and efficient data processing
### 📋 Default Custom Plan
The **Custom plan** is now the default option, specifically designed for 5-hour Claude Code sessions. It monitors three critical metrics:
- **Token usage** - Tracks your token consumption
- **Messages usage** - Monitors message count
- **Cost usage** - The most important metric for long sessions
The Custom plan automatically adapts to your usage patterns by analyzing all your sessions from the last 192 hours (8 days) and calculating personalized limits based on your actual usage. This ensures accurate predictions and warnings tailored to your specific workflow.
## 🚀 Installation
### ⚡ Modern Installation with uv (Recommended)
**Why uv is the best choice:**
- ✅ Creates isolated environments automatically (no system conflicts)
- ✅ No Python version issues
- ✅ No "externally-managed-environment" errors
- ✅ Easy updates and uninstallation
- ✅ Works on all platforms
The fastest and easiest way to install and use the monitor:
[](https://pypi.org/project/claude-monitor/)
#### Install from PyPI
```bash
# Install directly from PyPI with uv (easiest)
uv tool install claude-monitor
# Run from anywhere
claude-monitor # or cmonitor, ccmonitor for short
```
#### Install from Source
```bash
# Clone and install from source
git clone https://github.com/Maciek-roboblog/Claude-Code-Usage-Monitor.git
cd Claude-Code-Usage-Monitor
uv tool install .
# Run from anywhere
claude-monitor
```
#### First-time uv users
If you don't have uv installed yet, get it with one command:
```bash
# 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
```
### 📦 Installation with pip
```bash
# Install from PyPI
pip install claude-monitor
# If claude-monitor command is not found, add ~/.local/bin to PATH:
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc # or restart your terminal
# Run from anywhere
claude-monitor # or cmonitor, ccmonitor for short
```
>
> **⚠️ PATH Setup**: If you see WARNING: The script claude-monitor is installed in '/home/username/.local/bin' which is not on PATH, follow the export PATH command above.
>
> **⚠️ Important**: On modern Linux distributions (Ubuntu 23.04+, Debian 12+, Fedora 38+), you may encounter an "externally-managed-environment" error. Instead of using --break-system-packages, we strongly recommend:
> 1. **Use uv instead** (see above) - it's safer and easier
> 2. **Use a virtual environment** - python3 -m venv myenv && source myenv/bin/activate
> 3. **Use pipx** - pipx install claude-usage-monitor
>
> See the Troubleshooting section for detailed solutions.
### 🛠️ Other Package Managers
#### pipx (Isolated Environments)
```bash
# Install with pipx
pipx install claude-monitor
# Run from anywhere
claude-monitor # or claude-code-monitor, cmonitor, ccmonitor, ccm for short
```
#### conda/mamba
```bash
# Install with pip in conda environment
pip install claude-monitor
# Run from anywhere
claude-monitor # or cmonitor, ccmonitor for short
```
## 📖 Usage
### Get Help
```bash
# Show help information
claude-monitor --help
```
#### Available Command-Line Parameters
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| --plan | string | custom | Plan type: pro, max5, max20, or custom |
| --custom-limit-tokens | int | None | Token limit for custom plan (must be > 0) |
| --timezone | string | auto | Timezone (auto-detected). Examples: UTC, America/New_York, Europe/London |
| --time-format | string | auto | Time format: 12h, 24h, or auto |
| --theme | string | auto | Display theme: light, dark, classic, or auto |
| --refresh-rate | int | 10 | Data refresh rate in seconds (1-60) |
| --refresh-per-second | float | 0.75 | Display refresh rate in Hz (0.1-20.0) |
| --reset-hour | int | None | Daily reset hour (0-23) |
| --log-level | string | INFO | Logging level: DEBUG, INFO, WARNING, ERROR, CRITICAL |
| --log-file | path | None | Log file path |
| --debug | flag | False | Enable debug logging |
| --version, -v | flag | False | Show version information |
| --clear | flag | False | Clear saved configuration |
#### Plan Options
| Plan | Token Limit | Cost Limit | Description |
|------|-------------|------------|-------------|
| pro | 19,000 | $18.00 | Claude Pro subscription |
| max5 | 88,000 | $35.00 | Claude Max5 subscription |
| max20 | 220,000 | $140.00 | Claude Max20 subscription |
| custom | P90-based | $200.00 | Auto-detection with ML analysis |
#### Command Aliases
The tool can be invoked using any of these commands:
- claude-monitor (primary)
- claude-code-monitor (full name)
- cmonitor (short)
- ccmonitor (short alternative)
- ccm (shortest)
#### Save Flags Feature
The monitor automatically saves your preferences to avoid re-specifying them on each run:
**What Gets Saved:**
- Theme preferences (--theme)
- Timezone settings (--timezone)
- Time format (--time-format)
- Refresh rates (--refresh-rate, --refresh-per-second)
- Reset hour (--reset-hour)
- Custom token limits (--custom-limit-tokens)
**Configuration Location:** ~/.claude-monitor/last_used.json
**Usage Examples:**
```bash
# First run - specify preferences
claude-monitor --plan pro --theme dark --timezone "America/New_York"
# Subsequent runs - preferences automatically restored
claude-monitor --plan pro
# Override saved settings for this session
claude-monitor --plan pro --theme light
# Clear all saved preferences
claude-monitor --clear
```
**Key Features:**
- ✅ Automatic parameter persistence between sessions
- ✅ CLI arguments always override saved settings
- ✅ Atomic file operations prevent corruption
- ✅ Graceful fallback if config files are damaged
- ✅ Plan parameter never saved (must specify each time)
### Basic Usage
#### With uv tool installation (Recommended)
```bash
# Default (Custom plan with auto-detection)
claude-monitor
# Alternative commands
claude-code-monitor # Full descriptive name
cmonitor # Short alias
ccmonitor # Short alternative
ccm # Shortest alias
# Exit the monitor
# Press Ctrl+C to gracefully exit
```
#### Development mode
If running from source, use python -m claude_monitor from the src/ directory.
### Configuration Options
#### Specify Your Plan
```bash
# Custom plan with P90 auto-detection (Default)
claude-monitor --plan custom
# Pro plan (~44,000 tokens)
claude-monitor --plan pro
# Max5 plan (~88,000 tokens)
claude-monitor --plan max5
# Max20 plan (~220,000 tokens)
claude-monitor --plan max20
# Custom plan with explicit token limit
claude-monitor --plan custom --custom-limit-tokens 100000
```
#### Custom Reset Times
```bash
# Reset at 3 AM
claude-monitor --reset-hour 3
# Reset at 10 PM
claude-monitor --reset-hour 22
```
#### Performance and Display Configuration
```bash
# Adjust refresh rate (1-60 seconds, default: 10)
claude-monitor --refresh-rate 5
# Adjust display refresh rate (0.1-20 Hz, default: 0.75)
claude-monitor --refresh-per-second 1.0
# Set time format (auto-detected by default)
claude-monitor --time-format 24h # or 12h
# Force specific theme
claude-monitor --theme dark # light, dark, classic, auto
# Clear saved configuration
claude-monitor --clear
```
#### Timezone Configuration
The default timezone is **auto-detected from your system**. Override with any valid timezone:
```bash
# Use US Eastern Time
claude-monitor --timezone America/New_York
# Use Tokyo time
claude-monitor --timezone Asia/Tokyo
# Use UTC
claude-monitor --timezone UTC
# Use London time
claude-monitor --timezone Europe/London
```
#### Logging and Debugging
```bash
# Enable debug logging
claude-monitor --debug
# Log to file
claude-monitor --log-file ~/.claude-monitor/logs/monitor.log
# Set log level
claude-monitor --log-level WARNING # DEBUG, INFO, WARNING, ERROR, CRITICAL
```
### Available Plans
| Plan | Token Limit | Best For |
|------|-----------------|----------|
| **custom** | P90 auto-detect | Intelligent limit detection (default) |
| **pro** | ~19,000 | Claude Pro subscription |
| **max5** | ~88,000 | Claude Max5 subscription |
| **max20** | ~220,000 | Claude Max20 subscription |
#### Advanced Plan Features
- **P90 Analysis**: Custom plan uses 90th percentile calculations from your usage history
- **Cost Tracking**: Model-specific pricing with cache token calculations
- **Limit Detection**: Intelligent threshold detection with 95% confidence
## 🚀 What's New in v3.0.0
### Major Changes
#### **Complete Architecture Rewrite**
- Modular design with Single Responsibility Principle (SRP) compliance
- Pydantic-based configuration with type safety and validation
- Advanced error handling with optional Sentry integration
- Comprehensive test suite with 100+ test cases
#### **Enhanced Functionality**
- **P90 Analysis**: Machine learning-based limit detection using 90th percentile calculations
- **Updated Plan Limits**: Pro (44k), Max5 (88k), Max20 (220k) tokens
- **Cost Analytics**: Model-specific pricing with cache token calculations
- **Rich UI**: WCAG-compliant themes with automatic terminal background detection
#### **New CLI Options**
- --refresh-per-second: Configurable display refresh rate (0.1-20 Hz)
- --time-format: Automatic 12h/24h format detection
- --custom-limit-tokens: Explicit token limits for custom plans
- --log-file and --log-level: Advanced logging capabilities
- --clear: Reset saved configuration
- Command aliases: claude-code-monitor, cmonitor, ccmonitor, ccm for convenience
#### **Breaking Changes**
- Package name changed from claude-usage-monitor to claude-monitor
- Default plan changed from pro to custom (with auto-detection)
- Minimum Python version increased to 3.9+
- Command structure updated (see examples above)
## ✨ Features & How It Works
### v3.0.0 Architecture Overview
The new version features a complete rewrite with modular architecture following Single Responsibility Principle (SRP):
### 🖥️ User Interface Layer
| Component | Description |
| -------------------- | --------------------- |
| **CLI Module** | Pydantic-based |
| **Settings/Config** | Type-safe |
| **Error Handling** | Sentry-ready |
| **Rich Terminal UI** | Adaptive Theme |
---
### 🎛️ Monitoring Orchestrator
| Component | Key Responsibilities |
| ------------------------ | ---------------------------------------------------------------- |
| **Central Control Hub** | Session Mgmt · Real-time Data Flow · Component Coordination |
| **Data Manager** | Cache Mgmt · File I/O · State Persist |
| **Session Monitor** | Real-time · 5 hr Windows · Token Track |
| **UI Controller** | Rich Display · Progress Bars · Theme System |
| **Analytics** | P90 Calculator · Burn Rate · Predictions |
---
### 🏗️ Foundation Layer
| Component | Core Features |
| ------------------- | ------------------------------------------------------- |
| **Core Models** | Session Data · Config Schema · Type Safety |
| **Analysis Engine** | ML Algorithms · Statistical · Forecasting |
| **Terminal Themes** | Auto-detection · WCAG Colors · Contrast Opt |
| **Claude API Data** | Token Tracking · Cost Calculator · Session Blocks |
---
**🔄 Data Flow:**
Claude Config Files → Data Layer → Analysis Engine → UI Components → Terminal Display
### Current Features
#### 🔄 Advanced Real-time Monitoring
- Configurable update intervals (1-60 seconds)
- High-precision display refresh (0.1-20 Hz)
- Intelligent change detection to minimize CPU usage
- Multi-threaded orchestration with callback system
#### 📊 Rich UI Components
- **Progress Bars**: WCAG-compliant color schemes with scientific contrast ratios
- **Data Tables**: Sortable columns with model-specific statistics
- **Layout Manager**: Responsive design that adapts to terminal size
- **Theme System**: Auto-detects terminal background for optimal readability
#### 🔮 Machine Learning Predictions
- **P90 Calculator**: 90th percentile analysis for intelligent limit detection
- **Burn Rate Analytics**: Multi-session consumption pattern analysis
- **Cost Projections**: Model-specific pricing with cache token calculations
- **Session Forecasting**: Predicts when sessions will expire based on usage patterns
#### 🤖 Intelligent Auto-Detection
- **Background Detection**: Automatically determines terminal theme (light/dark)
- **System Integration**: Auto-detects timezone and time format preferences
- **Plan Recognition**: Analyzes usage patterns to suggest optimal plans
- **Limit Discovery**: Scans historical data to find actual token limits
### 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
**Example Session Timeline:**
10:30 AM - First message (Session A starts at 10 AM)
03:00 PM - Session A expires (5 hours later)
12:15 PM - First message (Session B starts 12PM)
05:15 PM - Session B expires (5 hours later 5PM)
#### 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
#### v3.0.0 Updated Plan Limits
| Plan | Limit (Tokens) | Cost Limit | Messages | Algorithm |
|------|----------------|------------|----------|-----------|
| **Claude Pro** | 19,000 | $18.00 | 250 | Fixed limit |
| **Claude Max5** | 88,000 | $35.00 | 1,000 | Fixed limit |
| **Claude Max20** | 220,000 | $140.00 | 2,000 | Fixed limit |
| **Custom** | P90-based | $200.00 | 250+ | Machine learning |
#### Advanced Limit Detection
- **P90 Analysis**: Uses 90th percentile of your historical usage
- **Confidence Threshold**: 95% accuracy in limit detection
- **Cache Support**: Includes cache creation and read token costs
- **Model-Specific**: Adapts to Claude 3.5, Claude 4, and future models
### Technical Requirements
#### Dependencies (v3.0.0)
```toml
# Core dependencies (automatically installed)
pytz>=2023.3 # Timezone handling
rich>=13.7.0 # Rich terminal UI
pydantic>=2.0.0 # Type validation
pydantic-settings>=2.0.0 # Configuration management
numpy>=1.21.0 # Statistical calculations
sentry-sdk>=1.40.0 # Error reporting (optional)
pyyaml>=6.0 # Configuration files
tzdata # Windows timezone data
```
#### Python Requirements
- **Minimum**: Python 3.9+
- **Recommended**: Python 3.11+
- **Tested on**: Python 3.9, 3.10, 3.11, 3.12, 3.13
### 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.
```bash
# 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.
```bash
# 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.
```bash
# 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.
```bash
# 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.
```bash
# Just run it with defaults
claude-monitor
# Press Ctrl+C after checking status
```
### Plan Selection Strategies
#### How to Choose Your Plan
**Start with Default (Recommended for New Users)**
```bash
# Pro plan detection with auto-switching
claude-monitor
```
- Monitor will detect if you exceed Pro limits
- Automatically switches to custom_max if needed
- Shows notification when switching occurs
**Known Subscription Users**
```bash
# If you know you have Max5
claude-monitor --plan max5
# If you know you have Max20
claude-monitor --plan max20
```
**Unknown Limits**
```bash
# Auto-detect from previous usage
claude-monitor --plan custom_max
```
### Best Practices
#### Setup Best Practices
1. **Start Early in Sessions**
```bash
# Begin monitoring when starting Claude work (uv installation)
claude-monitor
# Or development mode
./claude_monitor.py
```
- Gives accurate session tracking from the start
- Better burn rate calculations
- Early warning for limit approaches
2. **Use Modern Installation (Recommended)**
```bash
# Easy installation and updates with uv
uv tool install claude-monitor
claude-monitor --plan max5
```
- Clean system installation
- Easy updates and maintenance
- Available from anywhere
3. **Custom Shell Alias (Legacy Setup)**
```bash
# 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
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**
```bash
# 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
3. **Timezone Awareness**
```bash
# 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
1. **Terminal Setup**
- Use terminals with at least 80 character width
- Enable color support for better visual feedback (check COLORTERM environment variable)
- Consider dedicated terminal window for monitoring
- Use terminals with truecolor support for best theme experience
2. **Workflow Integration**
```bash
# Start monitoring with your development session (uv installation)
tmux new-session -d -s claude-monitor 'claude-monitor'
# Or development mode
tmux new-session -d -s claude-monitor './claude_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**
```bash
# Setup for sustained development
claude-monitor --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**
```bash
# Flexible setup for learning
claude-monitor --plan pro
```
**Sprint Development**
```bash
# High-intensity development setup
claude-monitor --plan max20 --reset-hour 6
```
## 🔧 Development Installation
For contributors and developers who want to work with the source code:
### Quick Start (Development/Testing)
```bash
# Clone the repository
git clone https://github.com/Maciek-roboblog/Claude-Code-Usage-Monitor.git
cd Claude-Code-Usage-Monitor
# Install in development mode
pip install -e .
# Run from source
python -m claude_monitor
```
### v3.0.0 Testing Features
The new version includes a comprehensive test suite:
- **100+ test cases** with full coverage
- **Unit tests** for all components
- **Integration tests** for end-to-end workflows
- **Performance tests** with benchmarking
- **Mock objects** for isolated testing
```bash
# Run tests
cd src/
python -m pytest
# Run with coverage
python -m pytest --cov=claude_monitor --cov-report=html
# Run specific test modules
python -m pytest tests/test_analysis.py -v
```
### Prerequisites
1. **Python 3.9+** installed on your system
2. **Git** for cloning the repository
### 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:
```bash
# 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:
```bash
# Install virtualenv via pip
pip install virtualenv
# Then create virtual environment with:
virtualenv venv
# instead of: python3 -m venv venv
```
#### Step-by-Step Setup
```bash
# 1. Clone the repository
git clone https://github.com/Maciek-roboblog/Claude-Code-Usage-Monitor.git
cd Claude-Code-Usage-Monitor
# 2. Create virtual environment
python3 -m venv venv
# Or if using virtualenv package:
# virtualenv venv
# 3. Activate virtual environment
# On Linux/Mac:
source venv/bin/activate
# On Windows:
# venv\Scripts\activate
# 4. Install Python dependencies
pip install pytz
pip install rich>=13.0.0
# 5. Make script executable (Linux/Mac only)
chmod +x claude_monitor.py
# 6. Run the monitor
python claude_monitor.py
```
#### Daily Usage
After initial setup, you only need:
```bash
# 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:
```bash
# 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
```
## Troubleshooting
### Installation Issues
#### "externally-managed-environment" Error
On modern Linux distributions (Ubuntu 23.04+, Debian 12+, Fedora 38+), you may encounter:
```
error: externally-managed-environment
× This environment is externally managed
```
**Solutions (in order of preference):**
1. **Use uv (Recommended)**
```bash
# Install uv first
curl -LsSf https://astral.sh/uv/install.sh | sh
# Then install with uv
uv tool install claude-monitor
```
2. **Use pipx (Isolated Environment)**
```bash
# Install pipx
sudo apt install pipx # Ubuntu/Debian
# or
python3 -m pip install --user pipx
# Install claude-monitor
pipx install claude-monitor
```
3. **Use virtual environment**
```bash
python3 -m venv myenv
source myenv/bin/activate
pip install claude-monitor
```
4. **Force installation (Not Recommended)**
```bash
pip install --user claude-monitor --break-system-packages
```
⚠️ **Warning**: This bypasses system protection and may cause conflicts. We strongly recommend using a virtual environment instead.
#### Command Not Found After pip Install
If claude-monitor command is not found after pip installation:
1. **Check if it's a PATH issue**
```bash
# Look for the warning message during pip install:
# WARNING: The script claude-monitor is installed in '/home/username/.local/bin' which is not on PATH
```
2. **Add to PATH**
```bash
# Add this to ~/.bashrc or ~/.zshrc
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
# Reload shell
source ~/.bashrc # or source ~/.zshrc
```
3. **Verify installation location**
```bash
# Find where pip installed the script
pip show -f claude-monitor | grep claude-monitor
```
4. **Run directly with Python**
```bash
python3 -m claude_monitor
```
#### Python Version Conflicts
If you have multiple Python versions:
1. **Check Python version**
```bash
python3 --version
pip3 --version
```
2. **Use specific Python version**
```bash
python3.11 -m pip install claude-monitor
python3.11 -m claude_monitor
```
3. **Use uv (handles Python versions automatically)**
```bash
uv tool install claude-monitor
```
### Runtime Issues
#### 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.
```bash
CLAUDE_CONFIG_DIR=~/.config/claude ./claude_monitor.py
```
## 📞 Contact
Have questions, suggestions, or want to collaborate? Feel free to reach out!
**📧 Email**: [maciek@roboblog.eu](mailto:maciek@roboblog.eu)
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](DEVELOPMENT.md)** - ML features, PyPI package, Docker plans
- **[Contributing Guide](CONTRIBUTING.md)** - How to contribute, development guidelines
- **[Troubleshooting](TROUBLESHOOTING.md)** - Common issues and solutions
## 📝 License
[MIT License](LICENSE) - feel free to use and modify as needed.
## 🤝 Contributors
- [@adawalli](https://github.com/adawalli)
- [@taylorwilsdon](https://github.com/taylorwilsdon)
- [@moneroexamples](https://github.com/moneroexamples)
Want to contribute? Check out our [Contributing Guide](CONTRIBUTING.md)!
## Star History
[](https://www.star-history.com/#Maciek-roboblog/Claude-Code-Usage-Monitor&Date)
---
<div align="center">
**⭐ Star this repo if you find it useful! ⭐**
[Report Bug](https://github.com/Maciek-roboblog/Claude-Code-Usage-Monitor/issues) • [Request Feature](https://github.com/Maciek-roboblog/Claude-Code-Usage-Monitor/issues) • [Contribute](CONTRIBUTING.md)
</div>
Raw data
{
"_id": null,
"home_page": null,
"name": "claude-monitor",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "Maciek <maciek@roboblog.eu>",
"keywords": "ai, analytics, claude, dashboard, developer-tools, monitoring, rich, terminal, token, usage",
"author": null,
"author_email": "Maciek <maciek@roboblog.eu>",
"download_url": "https://files.pythonhosted.org/packages/58/ce/8bb3d467fdc45bb19235e6cb23681728b947b19d24b76ee14c2cacd62c77/claude_monitor-3.0.3.tar.gz",
"platform": null,
"description": "# \ud83c\udfaf Claude Code Usage Monitor\n[](https://pypi.org/project/claude-monitor/)\n[](https://python.org)\n[](https://opensource.org/licenses/MIT)\n[](http://makeapullrequest.com)\n[](https://codecov.io/gh/Maciek-roboblog/Claude-Code-Usage-Monitor)\n\nA beautiful real-time terminal monitoring tool for Claude AI token usage with advanced analytics, machine learning-based predictions, and Rich UI. Track your token consumption, burn rate, cost analysis, and get intelligent predictions about session limits.\n\n\n\n---\n\n## \ud83d\udcd1 Table of Contents\n\n- [\u2728 Key Features](#-key-features)\n- [\ud83d\ude80 Installation](#-installation)\n - [\u26a1 Modern Installation with uv (Recommended)](#-modern-installation-with-uv-recommended)\n - [\ud83d\udce6 Installation with pip](#-installation-with-pip)\n - [\ud83d\udee0\ufe0f Other Package Managers](#\ufe0f-other-package-managers)\n- [\ud83d\udcd6 Usage](#-usage)\n - [Get Help](#get-help)\n - [Basic Usage](#basic-usage)\n - [Configuration Options](#configuration-options)\n - [Available Plans](#available-plans)\n- [\ud83d\ude4f Please Help Test This Release!](#-please-help-test-this-release)\n- [\u2728 Features & How It Works](#-features--how-it-works)\n - [Current Features](#current-features)\n - [Understanding Claude Sessions](#understanding-claude-sessions)\n - [Token Limits by Plan](#token-limits-by-plan)\n - [Smart Detection Features](#smart-detection-features)\n- [\ud83d\ude80 Usage Examples](#-usage-examples)\n - [Common Scenarios](#common-scenarios)\n - [Best Practices](#best-practices)\n- [\ud83d\udd27 Development Installation](#-development-installation)\n- [Troubleshooting](#troubleshooting)\n - [Installation Issues](#installation-issues)\n - [Runtime Issues](#runtime-issues)\n- [\ud83d\udcde Contact](#-contact)\n- [\ud83d\udcda Additional Documentation](#-additional-documentation)\n- [\ud83d\udcdd License](#-license)\n- [\ud83e\udd1d Contributors](#-contributors)\n- [\ud83d\ude4f Acknowledgments](#-acknowledgments)\n\n\n\n## \u2728 Key Features\n\n### \ud83d\ude80 **v3.0.0 Major Update - Complete Architecture Rewrite**\n\n- **\ud83d\udd2e ML-based predictions** - P90 percentile calculations and intelligent session limit detection\n- **\ud83d\udd04 Real-time monitoring** - Configurable refresh rates (0.1-20 Hz) with intelligent display updates\n- **\ud83d\udcca Advanced Rich UI** - Beautiful color-coded progress bars, tables, and layouts with WCAG-compliant contrast\n- **\ud83e\udd16 Smart auto-detection** - Automatic plan switching with custom limit discovery\n- **\ud83d\udccb Enhanced plan support** - Updated limits: Pro (44k), Max5 (88k), Max20 (220k), Custom (P90-based)\n- **\u26a0\ufe0f Advanced warning system** - Multi-level alerts with cost and time predictions\n- **\ud83d\udcbc Professional Architecture** - Modular design with Single Responsibility Principle (SRP) compliance\n- **\ud83c\udfa8 Intelligent theming** - Scientific color schemes with automatic terminal background detection\n- **\u23f0 Advanced scheduling** - Auto-detected system timezone and time format preferences\n- **\ud83d\udcc8 Cost analytics** - Model-specific pricing with cache token calculations\n- **\ud83d\udd27 Pydantic validation** - Type-safe configuration with automatic validation\n- **\ud83d\udcdd Comprehensive logging** - Optional file logging with configurable levels\n- **\ud83e\uddea Extensive testing** - 100+ test cases with full coverage\n- **\ud83c\udfaf Error reporting** - Optional Sentry integration for production monitoring\n- **\u26a1 Performance optimized** - Advanced caching and efficient data processing\n\n### \ud83d\udccb Default Custom Plan\n\nThe **Custom plan** is now the default option, specifically designed for 5-hour Claude Code sessions. It monitors three critical metrics:\n- **Token usage** - Tracks your token consumption\n- **Messages usage** - Monitors message count\n- **Cost usage** - The most important metric for long sessions\n\nThe Custom plan automatically adapts to your usage patterns by analyzing all your sessions from the last 192 hours (8 days) and calculating personalized limits based on your actual usage. This ensures accurate predictions and warnings tailored to your specific workflow.\n\n\n## \ud83d\ude80 Installation\n### \u26a1 Modern Installation with uv (Recommended)\n\n**Why uv is the best choice:**\n- \u2705 Creates isolated environments automatically (no system conflicts)\n- \u2705 No Python version issues\n- \u2705 No \"externally-managed-environment\" errors\n- \u2705 Easy updates and uninstallation\n- \u2705 Works on all platforms\n\nThe fastest and easiest way to install and use the monitor:\n\n[](https://pypi.org/project/claude-monitor/)\n\n#### Install from PyPI\n\n```bash\n# Install directly from PyPI with uv (easiest)\nuv tool install claude-monitor\n\n# Run from anywhere\nclaude-monitor # or cmonitor, ccmonitor for short\n```\n\n\n#### Install from Source\n\n```bash\n# Clone and install from source\ngit clone https://github.com/Maciek-roboblog/Claude-Code-Usage-Monitor.git\ncd Claude-Code-Usage-Monitor\nuv tool install .\n\n# Run from anywhere\nclaude-monitor\n```\n\n\n#### First-time uv users\nIf you don't have uv installed yet, get it with one command:\n\n```bash\n# On Linux/macOS:\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# On Windows:\npowershell -ExecutionPolicy ByPass -c \"irm https://astral.sh/uv/install.ps1 | iex\"\n\n# After installation, restart your terminal\n```\n\n\n### \ud83d\udce6 Installation with pip\n\n```bash\n# Install from PyPI\npip install claude-monitor\n\n# If claude-monitor command is not found, add ~/.local/bin to PATH:\necho 'export PATH=\"$HOME/.local/bin:$PATH\"' >> ~/.bashrc\nsource ~/.bashrc # or restart your terminal\n\n# Run from anywhere\nclaude-monitor # or cmonitor, ccmonitor for short\n```\n\n\n>\n> **\u26a0\ufe0f PATH Setup**: If you see WARNING: The script claude-monitor is installed in '/home/username/.local/bin' which is not on PATH, follow the export PATH command above.\n>\n> **\u26a0\ufe0f Important**: On modern Linux distributions (Ubuntu 23.04+, Debian 12+, Fedora 38+), you may encounter an \"externally-managed-environment\" error. Instead of using --break-system-packages, we strongly recommend:\n> 1. **Use uv instead** (see above) - it's safer and easier\n> 2. **Use a virtual environment** - python3 -m venv myenv && source myenv/bin/activate\n> 3. **Use pipx** - pipx install claude-usage-monitor\n>\n> See the Troubleshooting section for detailed solutions.\n\n### \ud83d\udee0\ufe0f Other Package Managers\n\n#### pipx (Isolated Environments)\n```bash\n# Install with pipx\npipx install claude-monitor\n\n# Run from anywhere\nclaude-monitor # or claude-code-monitor, cmonitor, ccmonitor, ccm for short\n```\n\n\n#### conda/mamba\n```bash\n# Install with pip in conda environment\npip install claude-monitor\n\n# Run from anywhere\nclaude-monitor # or cmonitor, ccmonitor for short\n```\n\n\n## \ud83d\udcd6 Usage\n\n### Get Help\n\n```bash\n# Show help information\nclaude-monitor --help\n```\n\n#### Available Command-Line Parameters\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| --plan | string | custom | Plan type: pro, max5, max20, or custom |\n| --custom-limit-tokens | int | None | Token limit for custom plan (must be > 0) |\n| --timezone | string | auto | Timezone (auto-detected). Examples: UTC, America/New_York, Europe/London |\n| --time-format | string | auto | Time format: 12h, 24h, or auto |\n| --theme | string | auto | Display theme: light, dark, classic, or auto |\n| --refresh-rate | int | 10 | Data refresh rate in seconds (1-60) |\n| --refresh-per-second | float | 0.75 | Display refresh rate in Hz (0.1-20.0) |\n| --reset-hour | int | None | Daily reset hour (0-23) |\n| --log-level | string | INFO | Logging level: DEBUG, INFO, WARNING, ERROR, CRITICAL |\n| --log-file | path | None | Log file path |\n| --debug | flag | False | Enable debug logging |\n| --version, -v | flag | False | Show version information |\n| --clear | flag | False | Clear saved configuration |\n\n#### Plan Options\n\n| Plan | Token Limit | Cost Limit | Description |\n|------|-------------|------------|-------------|\n| pro | 19,000 | $18.00 | Claude Pro subscription |\n| max5 | 88,000 | $35.00 | Claude Max5 subscription |\n| max20 | 220,000 | $140.00 | Claude Max20 subscription |\n| custom | P90-based | $200.00 | Auto-detection with ML analysis |\n\n#### Command Aliases\n\nThe tool can be invoked using any of these commands:\n- claude-monitor (primary)\n- claude-code-monitor (full name)\n- cmonitor (short)\n- ccmonitor (short alternative)\n- ccm (shortest)\n\n#### Save Flags Feature\n\nThe monitor automatically saves your preferences to avoid re-specifying them on each run:\n\n**What Gets Saved:**\n- Theme preferences (--theme)\n- Timezone settings (--timezone)\n- Time format (--time-format)\n- Refresh rates (--refresh-rate, --refresh-per-second)\n- Reset hour (--reset-hour)\n- Custom token limits (--custom-limit-tokens)\n\n**Configuration Location:** ~/.claude-monitor/last_used.json\n\n**Usage Examples:**\n```bash\n# First run - specify preferences\nclaude-monitor --plan pro --theme dark --timezone \"America/New_York\"\n\n# Subsequent runs - preferences automatically restored\nclaude-monitor --plan pro\n\n# Override saved settings for this session\nclaude-monitor --plan pro --theme light\n\n# Clear all saved preferences\nclaude-monitor --clear\n```\n\n**Key Features:**\n- \u2705 Automatic parameter persistence between sessions\n- \u2705 CLI arguments always override saved settings\n- \u2705 Atomic file operations prevent corruption\n- \u2705 Graceful fallback if config files are damaged\n- \u2705 Plan parameter never saved (must specify each time)\n\n### Basic Usage\n\n#### With uv tool installation (Recommended)\n```bash\n# Default (Custom plan with auto-detection)\nclaude-monitor\n\n# Alternative commands\nclaude-code-monitor # Full descriptive name\ncmonitor # Short alias\nccmonitor # Short alternative\nccm # Shortest alias\n\n# Exit the monitor\n# Press Ctrl+C to gracefully exit\n```\n\n#### Development mode\nIf running from source, use python -m claude_monitor from the src/ directory.\n\n### Configuration Options\n\n#### Specify Your Plan\n\n```bash\n# Custom plan with P90 auto-detection (Default)\nclaude-monitor --plan custom\n\n# Pro plan (~44,000 tokens)\nclaude-monitor --plan pro\n\n# Max5 plan (~88,000 tokens)\nclaude-monitor --plan max5\n\n# Max20 plan (~220,000 tokens)\nclaude-monitor --plan max20\n\n# Custom plan with explicit token limit\nclaude-monitor --plan custom --custom-limit-tokens 100000\n```\n\n#### Custom Reset Times\n\n```bash\n# Reset at 3 AM\nclaude-monitor --reset-hour 3\n\n# Reset at 10 PM\nclaude-monitor --reset-hour 22\n```\n\n#### Performance and Display Configuration\n\n```bash\n# Adjust refresh rate (1-60 seconds, default: 10)\nclaude-monitor --refresh-rate 5\n\n# Adjust display refresh rate (0.1-20 Hz, default: 0.75)\nclaude-monitor --refresh-per-second 1.0\n\n# Set time format (auto-detected by default)\nclaude-monitor --time-format 24h # or 12h\n\n# Force specific theme\nclaude-monitor --theme dark # light, dark, classic, auto\n\n# Clear saved configuration\nclaude-monitor --clear\n```\n\n#### Timezone Configuration\n\nThe default timezone is **auto-detected from your system**. Override with any valid timezone:\n\n```bash\n# Use US Eastern Time\nclaude-monitor --timezone America/New_York\n\n# Use Tokyo time\nclaude-monitor --timezone Asia/Tokyo\n\n# Use UTC\nclaude-monitor --timezone UTC\n\n# Use London time\nclaude-monitor --timezone Europe/London\n```\n\n#### Logging and Debugging\n\n```bash\n# Enable debug logging\nclaude-monitor --debug\n\n# Log to file\nclaude-monitor --log-file ~/.claude-monitor/logs/monitor.log\n\n# Set log level\nclaude-monitor --log-level WARNING # DEBUG, INFO, WARNING, ERROR, CRITICAL\n```\n\n### Available Plans\n\n| Plan | Token Limit | Best For |\n|------|-----------------|----------|\n| **custom** | P90 auto-detect | Intelligent limit detection (default) |\n| **pro** | ~19,000 | Claude Pro subscription |\n| **max5** | ~88,000 | Claude Max5 subscription |\n| **max20** | ~220,000 | Claude Max20 subscription |\n\n#### Advanced Plan Features\n\n- **P90 Analysis**: Custom plan uses 90th percentile calculations from your usage history\n- **Cost Tracking**: Model-specific pricing with cache token calculations\n- **Limit Detection**: Intelligent threshold detection with 95% confidence\n\n\n## \ud83d\ude80 What's New in v3.0.0\n\n### Major Changes\n\n#### **Complete Architecture Rewrite**\n- Modular design with Single Responsibility Principle (SRP) compliance\n- Pydantic-based configuration with type safety and validation\n- Advanced error handling with optional Sentry integration\n- Comprehensive test suite with 100+ test cases\n\n#### **Enhanced Functionality**\n- **P90 Analysis**: Machine learning-based limit detection using 90th percentile calculations\n- **Updated Plan Limits**: Pro (44k), Max5 (88k), Max20 (220k) tokens\n- **Cost Analytics**: Model-specific pricing with cache token calculations\n- **Rich UI**: WCAG-compliant themes with automatic terminal background detection\n\n#### **New CLI Options**\n- --refresh-per-second: Configurable display refresh rate (0.1-20 Hz)\n- --time-format: Automatic 12h/24h format detection\n- --custom-limit-tokens: Explicit token limits for custom plans\n- --log-file and --log-level: Advanced logging capabilities\n- --clear: Reset saved configuration\n- Command aliases: claude-code-monitor, cmonitor, ccmonitor, ccm for convenience\n\n#### **Breaking Changes**\n- Package name changed from claude-usage-monitor to claude-monitor\n- Default plan changed from pro to custom (with auto-detection)\n- Minimum Python version increased to 3.9+\n- Command structure updated (see examples above)\n\n\n## \u2728 Features & How It Works\n\n### v3.0.0 Architecture Overview\n\nThe new version features a complete rewrite with modular architecture following Single Responsibility Principle (SRP):\n\n### \ud83d\udda5\ufe0f User Interface Layer\n\n| Component | Description |\n| -------------------- | --------------------- |\n| **CLI Module** | Pydantic-based |\n| **Settings/Config** | Type-safe |\n| **Error Handling** | Sentry-ready |\n| **Rich Terminal UI** | Adaptive Theme |\n\n---\n\n### \ud83c\udf9b\ufe0f Monitoring Orchestrator\n\n| Component | Key Responsibilities |\n| ------------------------ | ---------------------------------------------------------------- |\n| **Central Control Hub** | Session Mgmt \u00b7 Real-time Data Flow \u00b7 Component Coordination |\n| **Data Manager** | Cache Mgmt \u00b7 File I/O \u00b7 State Persist |\n| **Session Monitor** | Real-time \u00b7 5 hr Windows \u00b7 Token Track |\n| **UI Controller** | Rich Display \u00b7 Progress Bars \u00b7 Theme System |\n| **Analytics** | P90 Calculator \u00b7 Burn Rate \u00b7 Predictions |\n\n---\n\n### \ud83c\udfd7\ufe0f Foundation Layer\n\n| Component | Core Features |\n| ------------------- | ------------------------------------------------------- |\n| **Core Models** | Session Data \u00b7 Config Schema \u00b7 Type Safety |\n| **Analysis Engine** | ML Algorithms \u00b7 Statistical \u00b7 Forecasting |\n| **Terminal Themes** | Auto-detection \u00b7 WCAG Colors \u00b7 Contrast Opt |\n| **Claude API Data** | Token Tracking \u00b7 Cost Calculator \u00b7 Session Blocks |\n\n---\n\n**\ud83d\udd04 Data Flow:**\nClaude Config Files \u2192 Data Layer \u2192 Analysis Engine \u2192 UI Components \u2192 Terminal Display\n\n\n### Current Features\n\n#### \ud83d\udd04 Advanced Real-time Monitoring\n- Configurable update intervals (1-60 seconds)\n- High-precision display refresh (0.1-20 Hz)\n- Intelligent change detection to minimize CPU usage\n- Multi-threaded orchestration with callback system\n\n#### \ud83d\udcca Rich UI Components\n- **Progress Bars**: WCAG-compliant color schemes with scientific contrast ratios\n- **Data Tables**: Sortable columns with model-specific statistics\n- **Layout Manager**: Responsive design that adapts to terminal size\n- **Theme System**: Auto-detects terminal background for optimal readability\n\n#### \ud83d\udd2e Machine Learning Predictions\n- **P90 Calculator**: 90th percentile analysis for intelligent limit detection\n- **Burn Rate Analytics**: Multi-session consumption pattern analysis\n- **Cost Projections**: Model-specific pricing with cache token calculations\n- **Session Forecasting**: Predicts when sessions will expire based on usage patterns\n\n#### \ud83e\udd16 Intelligent Auto-Detection\n- **Background Detection**: Automatically determines terminal theme (light/dark)\n- **System Integration**: Auto-detects timezone and time format preferences\n- **Plan Recognition**: Analyzes usage patterns to suggest optimal plans\n- **Limit Discovery**: Scans historical data to find actual token limits\n\n### Understanding Claude Sessions\n\n#### How Claude Code Sessions Work\n\nClaude Code operates on a **5-hour rolling session window system**:\n\n1. **Session Start**: Begins with your first message to Claude\n2. **Session Duration**: Lasts exactly 5 hours from that first message\n3. **Token Limits**: Apply within each 5-hour session window\n4. **Multiple Sessions**: Can have several active sessions simultaneously\n5. **Rolling Windows**: New sessions can start while others are still active\n\n#### Session Reset Schedule\n\n**Example Session Timeline:**\n10:30 AM - First message (Session A starts at 10 AM)\n03:00 PM - Session A expires (5 hours later)\n\n12:15 PM - First message (Session B starts 12PM)\n05:15 PM - Session B expires (5 hours later 5PM)\n\n\n#### Burn Rate Calculation\n\nThe monitor calculates burn rate using sophisticated analysis:\n\n1. **Data Collection**: Gathers token usage from all sessions in the last hour\n2. **Pattern Analysis**: Identifies consumption trends across overlapping sessions\n3. **Velocity Tracking**: Calculates tokens consumed per minute\n4. **Prediction Engine**: Estimates when current session tokens will deplete\n5. **Real-time Updates**: Adjusts predictions as usage patterns change\n\n### Token Limits by Plan\n\n#### v3.0.0 Updated Plan Limits\n\n| Plan | Limit (Tokens) | Cost Limit | Messages | Algorithm |\n|------|----------------|------------|----------|-----------|\n| **Claude Pro** | 19,000 | $18.00 | 250 | Fixed limit |\n| **Claude Max5** | 88,000 | $35.00 | 1,000 | Fixed limit |\n| **Claude Max20** | 220,000 | $140.00 | 2,000 | Fixed limit |\n| **Custom** | P90-based | $200.00 | 250+ | Machine learning |\n\n#### Advanced Limit Detection\n\n- **P90 Analysis**: Uses 90th percentile of your historical usage\n- **Confidence Threshold**: 95% accuracy in limit detection\n- **Cache Support**: Includes cache creation and read token costs\n- **Model-Specific**: Adapts to Claude 3.5, Claude 4, and future models\n\n### Technical Requirements\n\n#### Dependencies (v3.0.0)\n\n```toml\n# Core dependencies (automatically installed)\npytz>=2023.3 # Timezone handling\nrich>=13.7.0 # Rich terminal UI\npydantic>=2.0.0 # Type validation\npydantic-settings>=2.0.0 # Configuration management\nnumpy>=1.21.0 # Statistical calculations\nsentry-sdk>=1.40.0 # Error reporting (optional)\npyyaml>=6.0 # Configuration files\ntzdata # Windows timezone data\n```\n\n#### Python Requirements\n\n- **Minimum**: Python 3.9+\n- **Recommended**: Python 3.11+\n- **Tested on**: Python 3.9, 3.10, 3.11, 3.12, 3.13\n\n### Smart Detection Features\n\n#### Automatic Plan Switching\n\nWhen using the default Pro plan:\n\n1. **Detection**: Monitor notices token usage exceeding 7,000\n2. **Analysis**: Scans previous sessions for actual limits\n3. **Switch**: Automatically changes to custom_max mode\n4. **Notification**: Displays clear message about the change\n5. **Continuation**: Keeps monitoring with new, higher limit\n\n#### Limit Discovery Process\n\nThe auto-detection system:\n\n1. **Scans History**: Examines all available session blocks\n2. **Finds Peaks**: Identifies highest token usage achieved\n3. **Validates Data**: Ensures data quality and recency\n4. **Sets Limits**: Uses discovered maximum as new limit\n5. **Learns Patterns**: Adapts to your actual usage capabilities\n\n\n## \ud83d\ude80 Usage Examples\n\n### Common Scenarios\n\n#### \ud83c\udf05 Morning Developer\n**Scenario**: You start work at 9 AM and want tokens to reset aligned with your schedule.\n\n```bash\n# Set custom reset time to 9 AM\n./claude_monitor.py --reset-hour 9\n\n# With your timezone\n./claude_monitor.py --reset-hour 9 --timezone US/Eastern\n```\n\n\n**Benefits**:\n- Reset times align with your work schedule\n- Better planning for daily token allocation\n- Predictable session windows\n\n#### \ud83c\udf19 Night Owl Coder\n**Scenario**: You often work past midnight and need flexible reset scheduling.\n\n```bash\n# Reset at midnight for clean daily boundaries\n./claude_monitor.py --reset-hour 0\n\n# Late evening reset (11 PM)\n./claude_monitor.py --reset-hour 23\n```\n\n\n**Strategy**:\n- Plan heavy coding sessions around reset times\n- Use late resets to span midnight work sessions\n- Monitor burn rate during peak hours\n\n#### \ud83d\udd04 Heavy User with Variable Limits\n**Scenario**: Your token limits seem to change, and you're not sure of your exact plan.\n\n```bash\n# Auto-detect your highest previous usage\nclaude-monitor --plan custom_max\n\n# Monitor with custom scheduling\nclaude-monitor --plan custom_max --reset-hour 6\n```\n\n\n**Approach**:\n- Let auto-detection find your real limits\n- Monitor for a week to understand patterns\n- Note when limits change or reset\n\n#### \ud83c\udf0d International User\n**Scenario**: You're working across different timezones or traveling.\n\n```bash\n# US East Coast\nclaude-monitor --timezone America/New_York\n\n# Europe\nclaude-monitor --timezone Europe/London\n\n# Asia Pacific\nclaude-monitor --timezone Asia/Singapore\n\n# UTC for international team coordination\nclaude-monitor --timezone UTC --reset-hour 12\n```\n\n\n#### \u26a1 Quick Check\n**Scenario**: You just want to see current status without configuration.\n\n```bash\n# Just run it with defaults\nclaude-monitor\n\n# Press Ctrl+C after checking status\n```\n\n\n### Plan Selection Strategies\n\n#### How to Choose Your Plan\n\n**Start with Default (Recommended for New Users)**\n```bash\n# Pro plan detection with auto-switching\nclaude-monitor\n```\n\n- Monitor will detect if you exceed Pro limits\n- Automatically switches to custom_max if needed\n- Shows notification when switching occurs\n\n**Known Subscription Users**\n```bash\n# If you know you have Max5\nclaude-monitor --plan max5\n\n# If you know you have Max20\nclaude-monitor --plan max20\n```\n\n\n**Unknown Limits**\n```bash\n# Auto-detect from previous usage\nclaude-monitor --plan custom_max\n```\n\n\n### Best Practices\n\n#### Setup Best Practices\n\n1. **Start Early in Sessions**\n\n```bash\n # Begin monitoring when starting Claude work (uv installation)\n claude-monitor\n\n # Or development mode\n ./claude_monitor.py\n ```\n\n - Gives accurate session tracking from the start\n - Better burn rate calculations\n - Early warning for limit approaches\n\n2. **Use Modern Installation (Recommended)**\n\n```bash\n # Easy installation and updates with uv\n uv tool install claude-monitor\n claude-monitor --plan max5\n ```\n\n - Clean system installation\n - Easy updates and maintenance\n - Available from anywhere\n\n3. **Custom Shell Alias (Legacy Setup)**\n\n```bash\n # Add to ~/.bashrc or ~/.zshrc (only for development setup)\n alias claude-monitor='cd ~/Claude-Code-Usage-Monitor && source venv/bin/activate && ./claude_monitor.py'\n ```\n\n\n#### Usage Best Practices\n\n1. **Monitor Burn Rate Velocity**\n - Watch for sudden spikes in token consumption\n - Adjust coding intensity based on remaining time\n - Plan big refactors around session resets\n\n2. **Strategic Session Planning**\n\n```bash\n # Plan heavy usage around reset times\n claude-monitor --reset-hour 9\n ```\n\n - Schedule large tasks after resets\n - Use lighter tasks when approaching limits\n - Leverage multiple overlapping sessions\n\n3. **Timezone Awareness**\n\n```bash\n # Always use your actual timezone\n claude-monitor --timezone Europe/Warsaw\n ```\n\n - Accurate reset time predictions\n - Better planning for work schedules\n - Correct session expiration estimates\n\n#### Optimization Tips\n\n1. **Terminal Setup**\n - Use terminals with at least 80 character width\n - Enable color support for better visual feedback (check COLORTERM environment variable)\n - Consider dedicated terminal window for monitoring\n - Use terminals with truecolor support for best theme experience\n\n2. **Workflow Integration**\n\n```bash\n # Start monitoring with your development session (uv installation)\n tmux new-session -d -s claude-monitor 'claude-monitor'\n\n # Or development mode\n tmux new-session -d -s claude-monitor './claude_monitor.py'\n\n # Check status anytime\n tmux attach -t claude-monitor\n ```\n\n\n3. **Multi-Session Strategy**\n - Remember sessions last exactly 5 hours\n - You can have multiple overlapping sessions\n - Plan work across session boundaries\n\n#### Real-World Workflows\n\n**Large Project Development**\n```bash\n# Setup for sustained development\nclaude-monitor --plan max20 --reset-hour 8 --timezone America/New_York\n```\n\n\n**Daily Routine**:\n1. **8:00 AM**: Fresh tokens, start major features\n2. **10:00 AM**: Check burn rate, adjust intensity\n3. **12:00 PM**: Monitor for afternoon session planning\n4. **2:00 PM**: New session window, tackle complex problems\n5. **4:00 PM**: Light tasks, prepare for evening session\n\n**Learning & Experimentation**\n```bash\n# Flexible setup for learning\nclaude-monitor --plan pro\n```\n\n\n**Sprint Development**\n```bash\n# High-intensity development setup\nclaude-monitor --plan max20 --reset-hour 6\n```\n\n\n## \ud83d\udd27 Development Installation\n\nFor contributors and developers who want to work with the source code:\n\n### Quick Start (Development/Testing)\n\n```bash\n# Clone the repository\ngit clone https://github.com/Maciek-roboblog/Claude-Code-Usage-Monitor.git\ncd Claude-Code-Usage-Monitor\n\n# Install in development mode\npip install -e .\n\n# Run from source\npython -m claude_monitor\n```\n\n\n### v3.0.0 Testing Features\n\nThe new version includes a comprehensive test suite:\n\n- **100+ test cases** with full coverage\n- **Unit tests** for all components\n- **Integration tests** for end-to-end workflows\n- **Performance tests** with benchmarking\n- **Mock objects** for isolated testing\n\n```bash\n# Run tests\ncd src/\npython -m pytest\n\n# Run with coverage\npython -m pytest --cov=claude_monitor --cov-report=html\n\n# Run specific test modules\npython -m pytest tests/test_analysis.py -v\n```\n\n\n### Prerequisites\n\n1. **Python 3.9+** installed on your system\n2. **Git** for cloning the repository\n\n\n### Virtual Environment Setup\n\n#### Why Use Virtual Environment?\n\nUsing a virtual environment is **strongly recommended** because:\n\n- **\ud83d\udee1\ufe0f Isolation**: Keeps your system Python clean and prevents dependency conflicts\n- **\ud83d\udce6 Portability**: Easy to replicate the exact environment on different machines\n- **\ud83d\udd04 Version Control**: Lock specific versions of dependencies for stability\n- **\ud83e\uddf9 Clean Uninstall**: Simply delete the virtual environment folder to remove everything\n- **\ud83d\udc65 Team Collaboration**: Everyone uses the same Python and package versions\n\n#### Installing virtualenv (if needed)\n\nIf you don't have venv module available:\n\n```bash\n# Ubuntu/Debian\nsudo apt-get update\nsudo apt-get install python3-venv\n\n# Fedora/RHEL/CentOS\nsudo dnf install python3-venv\n\n# macOS (usually comes with Python)\n# If not available, install Python via Homebrew:\nbrew install python3\n\n# Windows (usually comes with Python)\n# If not available, reinstall Python from python.org\n# Make sure to check \"Add Python to PATH\" during installation\n```\n\n\nAlternatively, use the virtualenv package:\n```bash\n# Install virtualenv via pip\npip install virtualenv\n\n# Then create virtual environment with:\nvirtualenv venv\n# instead of: python3 -m venv venv\n```\n\n\n#### Step-by-Step Setup\n\n```bash\n# 1. Clone the repository\ngit clone https://github.com/Maciek-roboblog/Claude-Code-Usage-Monitor.git\ncd Claude-Code-Usage-Monitor\n\n# 2. Create virtual environment\npython3 -m venv venv\n# Or if using virtualenv package:\n# virtualenv venv\n\n# 3. Activate virtual environment\n# On Linux/Mac:\nsource venv/bin/activate\n# On Windows:\n# venv\\Scripts\\activate\n\n# 4. Install Python dependencies\npip install pytz\npip install rich>=13.0.0\n# 5. Make script executable (Linux/Mac only)\nchmod +x claude_monitor.py\n\n# 6. Run the monitor\npython claude_monitor.py\n```\n\n\n#### Daily Usage\n\nAfter initial setup, you only need:\n\n```bash\n# Navigate to project directory\ncd Claude-Code-Usage-Monitor\n\n# Activate virtual environment\nsource venv/bin/activate # Linux/Mac\n# venv\\Scripts\\activate # Windows\n\n# Run monitor\n./claude_monitor.py # Linux/Mac\n# python claude_monitor.py # Windows\n\n# When done, deactivate\ndeactivate\n```\n\n\n#### Pro Tip: Shell Alias\n\nCreate an alias for quick access:\n```bash\n# Add to ~/.bashrc or ~/.zshrc\nalias claude-monitor='cd ~/Claude-Code-Usage-Monitor && source venv/bin/activate && ./claude_monitor.py'\n\n# Then just run:\nclaude-monitor\n```\n\n\n## Troubleshooting\n\n### Installation Issues\n\n#### \"externally-managed-environment\" Error\n\nOn modern Linux distributions (Ubuntu 23.04+, Debian 12+, Fedora 38+), you may encounter:\n```\nerror: externally-managed-environment\n\u00d7 This environment is externally managed\n```\n\n\n**Solutions (in order of preference):**\n\n1. **Use uv (Recommended)**\n\n```bash\n # Install uv first\n curl -LsSf https://astral.sh/uv/install.sh | sh\n\n # Then install with uv\n uv tool install claude-monitor\n ```\n\n\n2. **Use pipx (Isolated Environment)**\n\n```bash\n # Install pipx\n sudo apt install pipx # Ubuntu/Debian\n # or\n python3 -m pip install --user pipx\n\n # Install claude-monitor\n pipx install claude-monitor\n ```\n\n\n3. **Use virtual environment**\n\n```bash\n python3 -m venv myenv\n source myenv/bin/activate\n pip install claude-monitor\n ```\n\n\n4. **Force installation (Not Recommended)**\n\n```bash\n pip install --user claude-monitor --break-system-packages\n ```\n\n \u26a0\ufe0f **Warning**: This bypasses system protection and may cause conflicts. We strongly recommend using a virtual environment instead.\n\n#### Command Not Found After pip Install\n\nIf claude-monitor command is not found after pip installation:\n\n1. **Check if it's a PATH issue**\n\n```bash\n # Look for the warning message during pip install:\n # WARNING: The script claude-monitor is installed in '/home/username/.local/bin' which is not on PATH\n ```\n\n\n2. **Add to PATH**\n\n```bash\n # Add this to ~/.bashrc or ~/.zshrc\n echo 'export PATH=\"$HOME/.local/bin:$PATH\"' >> ~/.bashrc\n\n # Reload shell\n source ~/.bashrc # or source ~/.zshrc\n ```\n\n\n3. **Verify installation location**\n\n```bash\n # Find where pip installed the script\n pip show -f claude-monitor | grep claude-monitor\n ```\n\n\n4. **Run directly with Python**\n\n```bash\n python3 -m claude_monitor\n ```\n\n\n#### Python Version Conflicts\n\nIf you have multiple Python versions:\n\n1. **Check Python version**\n\n```bash\n python3 --version\n pip3 --version\n ```\n\n\n2. **Use specific Python version**\n\n```bash\n python3.11 -m pip install claude-monitor\n python3.11 -m claude_monitor\n ```\n\n\n3. **Use uv (handles Python versions automatically)**\n\n```bash\n uv tool install claude-monitor\n ```\n\n\n### Runtime Issues\n\n#### No active session found\nIf you encounter the error No active session found, please follow these steps:\n\n1. **Initial Test**:\n 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.\n\n2. **Configuration Path**:\n 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.\n\n```bash\nCLAUDE_CONFIG_DIR=~/.config/claude ./claude_monitor.py\n```\n\n\n\n## \ud83d\udcde Contact\n\nHave questions, suggestions, or want to collaborate? Feel free to reach out!\n\n**\ud83d\udce7 Email**: [maciek@roboblog.eu](mailto:maciek@roboblog.eu)\n\nWhether 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!\n\n\n## \ud83d\udcda Additional Documentation\n\n- **[Development Roadmap](DEVELOPMENT.md)** - ML features, PyPI package, Docker plans\n- **[Contributing Guide](CONTRIBUTING.md)** - How to contribute, development guidelines\n- **[Troubleshooting](TROUBLESHOOTING.md)** - Common issues and solutions\n\n\n## \ud83d\udcdd License\n\n[MIT License](LICENSE) - feel free to use and modify as needed.\n\n## \ud83e\udd1d Contributors\n\n- [@adawalli](https://github.com/adawalli)\n- [@taylorwilsdon](https://github.com/taylorwilsdon)\n- [@moneroexamples](https://github.com/moneroexamples)\n\nWant to contribute? Check out our [Contributing Guide](CONTRIBUTING.md)!\n\n\n## Star History\n\n[](https://www.star-history.com/#Maciek-roboblog/Claude-Code-Usage-Monitor&Date)\n\n---\n\n<div align=\"center\">\n\n**\u2b50 Star this repo if you find it useful! \u2b50**\n\n[Report Bug](https://github.com/Maciek-roboblog/Claude-Code-Usage-Monitor/issues) \u2022 [Request Feature](https://github.com/Maciek-roboblog/Claude-Code-Usage-Monitor/issues) \u2022 [Contribute](CONTRIBUTING.md)\n\n</div>\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A real-time terminal monitoring tool for Claude Code token usage with advanced analytics and Rich UI",
"version": "3.0.3",
"project_urls": {
"Discussions": "https://github.com/Maciek-roboblog/Claude-Code-Usage-Monitor/discussions",
"Release Notes": "https://github.com/Maciek-roboblog/Claude-Code-Usage-Monitor/releases",
"changelog": "https://github.com/Maciek-roboblog/Claude-Code-Usage-Monitor/blob/main/CHANGELOG.md",
"documentation": "https://github.com/Maciek-roboblog/Claude-Code-Usage-Monitor#readme",
"homepage": "https://github.com/Maciek-roboblog/Claude-Code-Usage-Monitor",
"issues": "https://github.com/Maciek-roboblog/Claude-Code-Usage-Monitor/issues",
"repository": "https://github.com/Maciek-roboblog/Claude-Code-Usage-Monitor.git"
},
"split_keywords": [
"ai",
" analytics",
" claude",
" dashboard",
" developer-tools",
" monitoring",
" rich",
" terminal",
" token",
" usage"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "7807aa6e69930e828adc159c69d3be8ba688dad3393724b02cf8ce0688456793",
"md5": "8cf4411f70574bbc5231b70f52e5bd7e",
"sha256": "785fac1d345ad1871931f661932efda8a3c34cf6efc4f4319e1ce068c24f86ab"
},
"downloads": -1,
"filename": "claude_monitor-3.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8cf4411f70574bbc5231b70f52e5bd7e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 85902,
"upload_time": "2025-07-14T01:08:24",
"upload_time_iso_8601": "2025-07-14T01:08:24.346876Z",
"url": "https://files.pythonhosted.org/packages/78/07/aa6e69930e828adc159c69d3be8ba688dad3393724b02cf8ce0688456793/claude_monitor-3.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "58ce8bb3d467fdc45bb19235e6cb23681728b947b19d24b76ee14c2cacd62c77",
"md5": "3654bdd73cfa0cf642d04d0c81b1b0b8",
"sha256": "a40fc3e1e619efc6d12e8de2388b639eb2a25ab64369a86718c1017add9d5940"
},
"downloads": -1,
"filename": "claude_monitor-3.0.3.tar.gz",
"has_sig": false,
"md5_digest": "3654bdd73cfa0cf642d04d0c81b1b0b8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 93587,
"upload_time": "2025-07-14T01:08:26",
"upload_time_iso_8601": "2025-07-14T01:08:26.055924Z",
"url": "https://files.pythonhosted.org/packages/58/ce/8bb3d467fdc45bb19235e6cb23681728b947b19d24b76ee14c2cacd62c77/claude_monitor-3.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-14 01:08:26",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Maciek-roboblog",
"github_project": "Claude-Code-Usage-Monitor",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "claude-monitor"
}
JSON
