Real-time Claude AI Token Usage Monitor

Master Your Claude AI Usage with Real-time Monitoring

For developers and heavy users of Claude AI, managing token consumption can be a critical challenge. Unexpectedly hitting rate limits can disrupt workflows and impact productivity. Introducing the Claude-Code-Usage-Monitor, a robust, open-source Python project designed to give you unparalleled control and insight into your Claude AI token usage.

What is Claude-Code-Usage-Monitor?

Developed by Maciek-roboblog, this intuitive terminal-based tool provides a real-time display of your Claude AI token consumption. It's more than just a counter; it offers predictive analytics, visual progress bars, and smart warning systems to alert you before you run out of tokens. Whether you're on a Pro, Max5, Max20 plan, or have variable custom limits, this monitor adapts to your needs.

Key Features That Empower Your Workflow:

• Real-time Monitoring: Updates every 3 seconds with smooth, flicker-free refresh, showing live token consumption across multiple sessions.
• Visual Progress Bars: Color-coded token and time progress bars offer immediate, at-a-glance understanding of your usage and remaining session time.
• Smart Predictions: Based on your current burn rate, the monitor accurately predicts when your tokens will deplete, helping you plan ahead.
• Auto-Detection System: Intelligently switches to custom_max mode if your usage exceeds standard plan limits, scanning previous sessions to discover your actual token boundaries.
• Multiple Plan Support: Seamlessly works with Claude Pro, Max5, Max20, and automatically detects custom limits based on your past usage.
• Advanced Warning System: Receive alerts when your tokens are close to depletion or if they're projected to run out before your session resets.
• Professional UI: Enjoy a clean, colorful, and highly readable terminal interface designed for efficiency.
• Customizable Scheduling: Set your own session reset times and timezones to align with your personal or team's workflow.

How It Works: Understanding Claude Sessions

Claude AI operates on a 5-hour rolling session window. This means each interaction starts a new 5-hour clock for token consumption. You can have multiple overlapping sessions, and your token refresh happens exactly 5 hours after your first message in each session. The Claude-Code-Usage-Monitor tracks these complex dynamics, calculating your 'burn rate' by analyzing token usage from all active sessions in the last hour to provide accurate predictions.

Installation and Getting Started:

Setting up the Claude-Code-Usage-Monitor is straightforward. The project emphasizes using a virtual environment for isolation and portability, preventing dependency conflicts with your system's Python installation.

Prerequisites:

• Python 3.6+
• Node.js (for ccusage CLI tool)

**Quick Production Setup (Recommended):

1. Install ccusage globally:

   npm install -g ccusage
   

2. Clone the repository:

   git clone https://github.com/Maciek-roboblog/Claude-Code-Usage-Monitor.git
   cd Claude-Code-Usage-Monitor
   

3. Create and activate a virtual environment:

   python3 -m venv venv
   # On Linux/Mac:
   source venv/bin/activate
   # On Windows:
   # venv\Scripts\activate
   

4. Install Python dependencies:

   pip install pytz
   

5. Run the monitor:

   python ccusage_monitor.py
   

For daily use, simply activate your virtual environment and run the main script. You can even set up a shell alias for quick access.

Configuration and Usage:

The monitor offers various configuration options via command-line arguments:

• Specify Your Plan: Use --plan pro, --plan max5, --plan max20, or --plan custom_max to match your Claude subscription.
• Custom Reset Times: Adjust session reset hours with --reset-hour <hour> (e.g., --reset-hour 9 for 9 AM).
• Timezone Configuration: Ensure accurate predictions by setting your timezone, e.g., --timezone US/Eastern or --timezone Asia/Tokyo.

This level of customization makes the Claude-Code-Usage-Monitor incredibly flexible, catering to different work schedules, international teams, and variable AI usage patterns.

Why You Need This Tool:

For anyone looking to optimize their interaction with Claude AI, avoid unexpected service interruptions, and gain a clearer understanding of their token expenditure, the Claude-Code-Usage-Monitor is an invaluable asset. Its intelligent predictions and professional interface transform complex token management into a simple, visual, and highly efficient process. This open-source project empowers you to be more productive and cost-effective in your AI-driven tasks.

Dive into the project, contribute, and take full control of your Claude AI usage today!