Claude-Code-Usage-Monitor
Real-time Claude Code usage monitor with predictions and warnings
What is Claude-Code-Usage-Monitor?
Real-time Claude Code usage monitor with predictions and warnings
Overview of Claude-Code-Usage-Monitor
What it is
Claude-Code-Usage-Monitor is a privacy-first usage monitor for Claude Code. It provides a live terminal monitor with official statusline rate limits, machine-readable state/export output, provenance labels, forecasting, and an opt-in local usage warehouse.
Key features
- Official-limit trust layer: captures Claude Code's official rate_limits via --statusline; stale or expired captures fall back to labeled local estimates.
- Machine-readable protocol: --once, --compact, and --write-state 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.
Use cases
Monitoring token, message, and cost usage during long Claude Code sessions. Tracking usage across multiple projects or directories. Generating usage reports for analysis or automation. Integrating with external tools via state files or JSON output.
Getting started
bash# Install from PyPI with uv (recommended)uv tool install claude-monitor# Run from anywhereclaude-monitorAlternatively, install with pip:bashpip install claude-monitorclaude-monitor
License and pricing
License: MIT. Pricing type: open source.
Based on the project's public README and repository metadata.