Maciek-roboblog /Claude-Code-Usage-Monitor
Real-time Claude Code usage monitor with predictions and warnings
★ 8,801⑂ 461👁 34⑃ 82● 134▤ 12
+0
Daily
8,801
stars
461
forks
34
watchers
82
prs
134
issues
12
releases
README
🎯 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. !Claude Token Monitor Screenshot --- 📑 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
Top issues
#158[BUG] Incorrect Cost Usage calculation when continuing work in a resumed session11 comments · 2025-09-18#31brew support?11 comments · 2025-06-20#212monitor dosnt look accurate3 comments · 2026-05-01#152Feature Request: Cross-device usage synchronization3 comments · 2025-09-01#235Persist an audit trail for extra-usage transitions and provider-reported billing state1 comments · 2026-07-27#231On Windows, CCMonitor is tryingm to access WSL?1 comments · 2026-07-18#206Debian Packaging1 comments · 2026-04-14#187API based claude code cost monitoring like LiteLLM1 comments · 2026-02-13
Discussions
#225SigRank — token-efficiency leaderboard that ranks operators, not just models0 comments · 2026-07-03#218ccline: type natural language at your zsh prompt, get AI answers — for Claude Code users0 comments · 2026-06-10#213Using Claude Code for investment analysis — options flow scanner + price alerts (open source)0 comments · 2026-05-13#205ESP32/RasPi Support1 comments · 2026-04-13#203Translating the 88k gauge into "Real-World Work" capacity0 comments · 2026-04-12#194Research request: what real value remains beyond /usage, /stats, and the native status line?7 comments · 2026-03-12#191Should I run it inside .ralph or from the parent level?0 comments · 2026-02-24#168Help calibrating actual usage and shown Usage?2 comments · 2025-10-14
Latest release
Release v4.0.0 v4.0.0 2026-06-27Bug Fixes - Model distribution shows all families: ModelUsageBar now renders every model family — Sonnet, Opus, Haiku, and an "Other" bucket for anything else — instead of only Sonnet/Opus. Haiku and other models no longer vanish from the usage bar or skew the displayed percentages. (124, 164) - Plan is now saved and restored: the selected --plan is persisted in last_used.json and reloaded on the next run; an explicit --plan on the command line still takes priority. (162) - Saved theme no longer overwritten: an explicitly chosen light/dark/classic theme is preserved across runs instead of bein