# Add to your Claude Code skills
git clone https://github.com/Maciek-roboblog/Claude-Code-Usage-Monitor
README.md
🎯 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.
📊 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:
Install from PyPI
# 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
# 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:
# 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
# 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:
Use uv instead (see above) - it's safer and easier
Use a virtual environment - python3 -m venv myenv && source myenv/bin/activate
Use pipx - pipx install claude-monitor
See the Troubleshooting section for detailed solutions.
🛠️ Other Package Managers
pipx (Isolated Environments)
# Install with pipx
pipx install claude-monitor
# Run from anywhere
claude-monitor # or claude-code-monitor, cmonitor, ccmonitor, ccm for short
conda/mamba
# Install with pip in conda environment
pip install claude-monitor
# Run from anywhere
claude-monitor # or cmonitor, ccmonitor for short
📖 Usage
Get Help
# 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) |
| --view | string | realtime | View type: realtime, daily, or monthly |
| --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 | (default) $50.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:
# 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)
# Default (Custom plan with auto-detection)
claude-monitor
# Alternative commands
claude-code-monitor # Full descr
The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
