🎯 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