🎯 Claude Code Usage Monitor

A privacy-first Claude Usage-Ops companion for Claude Code. It combines a Rich live terminal monitor with official statusline rate_limits, machine-readable state/export output, provenance labels, forecasting, and an opt-in local usage warehouse.

📑 Table of Contents

• ✨ Key Features
• 🚀 Installation
  • ⚡ Modern Installation with uv (Recommended)
  • 📦 Installation with pip
  • 🛠️ Other Package Managers
• 📖 Usage
  • Get Help
  • Basic Usage
  • Configuration Options
  • Available Plans
• 🙏 Please Help Test This Release!
• ✨ Features & How It Works
  • Current Features
  • Understanding Claude Sessions
  • Token Limits by Plan
  • Smart Detection Features
• 🚀 Usage Examples
  • Common Scenarios
  • Best Practices
• 🔧 Development Installation
• Troubleshooting
  • Installation Issues
  • Runtime Issues
• 📞 Contact
• Related Tools
• 📚 Additional Documentation
• 📝 License
• 🤝 Contributors
• 🙏 Acknowledgments

✨ Key Features

🚀 v4.0.0 Major Update - Usage Ops Companion

• 🔎 Official-limit trust layer - --statusline captures Claude Code's official rate_limits; stale or expired captures fall back to labeled local estimates.
• 📦 Machine-readable protocol - --once, --compact, and --write-state all use one versioned snapshot builder with automation exit codes.
• 🏷️ Provenance labels - exported and displayed numbers distinguish official, local_estimate, experimental, and unknown confidence.
• 📈 Persistent usage warehouse - opt-in local history survives Claude's 30-day cleanup with project/model/day dimensions and CSV/JSON reports.
• 🧭 Forecasting and pace - reset-aware pace, date-context forecasts, official-only weekly percentages, and limit-hit freeze behavior.
• 🧩 Multi-source input - --data-paths, CLAUDE_CONFIG_DIR, and WSL discovery can scan multiple directories without merging unrelated accounts into one 5-hour window.
• 🖥️ Rich UI parity - live Rich output, rich one-shot output, compact output, state files, and exports use the same snapshot contract.
• 🧰 External companion boundary - GUIs, trays, provider adapters, and status bars should consume --write-state or --once --output json.
• 🧪 Regression coverage - the non-integration suite now covers the trust layer, state protocol, warehouse, reports, title updates, multi-source paths, and timezone edge cases.

📋 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:

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

Plan Options

|