This tool provides real-time monitoring of Claude AI token usage, offering predictions and warnings for users to manage their consumption effectively. It targets developers and power users of Claude AI who need to track their usage against various plan limits and session timings. The primary benefit is preventing unexpected token exhaustion and enabling better planning of AI-driven tasks.

How It Works

The monitor tracks token usage across Claude sessions, which operate on a 5-hour rolling window. It calculates a burn rate based on recent activity and uses this to predict when current token limits will be reached. The tool features smart detection to automatically switch to higher token limits (like custom_max) if usage exceeds the default pro plan, and it can be configured with custom reset times and timezones for personalized tracking.

Quick Start & Requirements

• Install: uv tool install claude-monitor (recommended) or pip install claude-monitor.
• Prerequisites: Python 3.7+. uv is recommended for easier dependency management and avoiding system conflicts.
• Usage: Run claude-monitor from the terminal.
• Configuration: Use flags like --plan <pro|max5|max20|custom_max>, --reset-hour <0-23>, and --timezone <Your/Timezone>.
• Docs: Contributing Guide, Troubleshooting, Contact

Highlighted Details

• Real-time monitoring updates every 3 seconds with smooth, flicker-free display.
• Visual progress bars for tokens and time, plus a burn rate indicator.
• Smart predictions warn if tokens will deplete before session reset.
• Automatic plan switching and limit discovery based on historical usage.
• Supports multiple plans (Pro, Max5, Max20, custom_max) and custom scheduling.

Maintenance & Community

The project is actively maintained by Maciek-roboblog. Users are encouraged to report bugs and request features via GitHub issues. Contact is available via email at maciek@roboblog.eu.

Licensing & Compatibility

The project is released under the MIT License, allowing for free use and modification, including for commercial purposes.

Limitations & Caveats

The README notes that the "LATEST STABLE VERSION FOR USE IS ON PYPI THIS VERSION IS LITTLE BIT TRICKY AND I WILL FIX IT 24.06.2025," suggesting potential instability or ongoing fixes. Users on modern Linux distributions might encounter "externally-managed-environment" errors if not using uv or virtual environments.