Claude Code Usage Monitor

Claude Code Usage Monitor is a privacy-first 'Usage-Ops' companion for Claude Code. It provides a live terminal monitor using the Rich library and includes features for tracking rate limits, forecasting usage, and maintaining a local usage warehouse.

Key capabilities include:

• Official-limit trust layer: Captures Claude Code's official rate_limits via --statusline.
• Machine-readable protocol: Supports --once, --compact, and --write-state for automation.
• Provenance labels: Distinguishes between official, local_estimate, experimental, and unknown data.
• Persistent usage warehouse: An opt-in local history that tracks project/model/day dimensions, surviving Claude's 30-day cleanup.
• Forecasting: Provides reset-aware pace and date-context forecasts.
• Multi-source input: Scans multiple directories via --data-paths or CLAUDE_CONFIG_DIR.

The recommended installation method uses uv to create isolated environments and avoid Python version or system environment conflicts.

1. Install uv (if not already installed)

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"

Note: Restart your terminal after installing uv.

2. Install the monitor

From PyPI (Easiest):

uv tool install claude-monitor

From Source:

git clone https://github.com/Maciek-roboblog/Claude-Code-Usage-Monitor.git
cd Claude-Code-Usage-Monitor
uv tool install .

3. Run the monitor

You can run the monitor using any of these commands: claude-monitor, cmonitor, or ccmonitor.

You can specify different subscription plans to align token limits and cost tracking with your Claude account.

To use a custom limit with the custom plan, use --custom-limit-tokens.

The monitor includes intelligent features to handle usage spikes:

• Automatic Plan Switching: When using the default Claude Pro plan, if token usage exceeds 7,000, the monitor scans previous sessions for actual limits and automatically switches to custom_max mode to prevent premature limit alerts.
• Limit Discovery: The system scans historical session blocks to identify peak token usage, validates the data, and sets the discovered maximum as the new limit using P90 (90th percentile) analysis.

To diagnose issues like thread errors or session detection problems, enable debug logging:

Full debug output to terminal:

claude-monitor --debug

Debug output to a specific file:

claude-monitor --debug --log-file /tmp/claude-debug.log

claude-monitor --debug --log-file ~/.claude-monitor/logs/debug.log

To ensure consistency and avoid synchronization issues, follow these rules:

• DO: Update the version only in pyproject.toml.
• DO: Use from claude_monitor import __version__ in all modules.
• DON'T: Hardcode version strings in any source code.
• DON'T: Define __version__ manually in __init__.py files.

The claude-monitor package uses a single source of truth for versioning. To update the version of the project, you must only modify the version field within the [project] section of pyproject.toml. All other modules and files will automatically reflect this change through the internal version detection system.

[project]
version = "3.0.0"

The recommended way to install the tool for easy updates and system-wide availability is using uv.

uv tool install claude-monitor
claude-monitor --plan max5

Ensure your environment meets the following requirements to run Claude Code Usage Monitor v4.0.0:

Python Requirements:

• Minimum: Python 3.9+
• Recommended: Python 3.11+
• Tested on: Python 3.9, 3.10, 3.11, 3.12, 3.13

Core Dependencies:

• pytz>=2023.3 (Timezone handling)
• rich>=13.7.0 (Terminal UI)
• pydantic>=2.0.0 (Type validation)
• pydantic-settings>=2.0.0 (Configuration)
• numpy>=1.21.0 (Statistics)
• pyyaml>=6.0 (Config files)
• tomli>=1.2.0 (Python <3.11 fallback)
• tzdata & tzlocal>=5.0 (Windows timezone support)
• wcwidth>=0.2.13 (Display width calculation)

When integrating claude-monitor with other tools or dashboards, use the following flags to get stable, non-interactive snapshots:

• JSON Snapshot: Use --once --output json for a single snapshot containing source, confidence, and provenance fields.
• Compact Output: Use --once --compact for a single-line status output.
• State File: Use --write-state --state-file <path> to write an atomically updated JSON state file for external tools/status bars.
• Statusline Hook: Use --statusline to capture official Claude Code rate_limits.

Exit Codes for --once mode:

• 0: OK
• 10: Near limit
• 11: Limit hit
• 20: Indeterminate/no active session
• 30: No data or config error

You can install the monitor using standard pip.

pip install claude-monitor

Note on PATH: If the claude-monitor command is not found after installation, you may need to add ~/.local/bin to your PATH:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Note for modern Linux (Ubuntu 23.04+, Debian 12+, Fedora 38+): If you encounter an "externally-managed-environment" error, it is highly recommended to use uv or pipx instead of pip to avoid breaking system packages.

For technical questions, feature requests, or security issues, use the following channels:

• Technical Questions: Open GitHub Issues with detailed context.
• Feature Requests: Use GitHub Discussions for community input.
• Security Issues: Email maciek@roboblog.eu directly.
• General Inquiries: Use GitHub discussions or repository issues.

Documentation Resources:

• User Guide: Refer to README.md for comprehensive usage examples.
• API Documentation: Available via auto-generated documentation from type hints.
• Contributing Guide: Refer to CONTRIBUTING.md for detailed workflows.
• Code Examples: Practical demonstrations are located in the /docs/examples/ directory.