Claude Code Usage Monitor

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