Claude Usage Monitor (Python Package)

Professional CLI tool for monitoring Claude AI token usage with zero external dependencies.

Credits & Attribution

This package is based on the original Claude-Code-Usage-Monitor by Maciej (maciek@roboblog.eu). This version transforms it into a zero-dependency pip-installable package while maintaining all original functionality.

Installation

# Run without installing anything (recommended)
uvx claude-usage-cli

# Or install it
uv tool install claude-usage-cli
pip install claude-usage-cli

The package has zero dependencies, so uvx fetches and runs it in one step with no virtualenv to manage:

uvx claude-usage-cli --summary
uvx claude-usage-cli --plan max20 --weekly-limit 4000

Quick Start

# Default monitoring (Pro plan)
claude-usage-cli

# Monitor with Max5 plan
claude-usage-cli --plan max5

# Custom timezone
claude-usage-cli --plan max20 --timezone US/Eastern

# Track against your own weekly limit
claude-usage-cli --weekly-limit 2000

# Show help
claude-usage-cli --help

Features

• 📊 Real-time token monitoring with visual progress bars
• 🔮 Smart predictions based on usage patterns
• 🎯 Multi-plan support (Pro, Max5, Max20, Custom)
• 🌍 Timezone handling for accurate reset times
• 🎨 Beautiful terminal UI with colors and emojis
• ⚡ Zero external dependencies - completely self-contained
• 🔄 Auto-refresh every 3 seconds
• 📱 Cross-platform (Windows, macOS, Linux)

Commands

# Basic usage
claude-usage-cli                          # Start monitoring with Pro plan
claude-usage-cli --plan max5              # Monitor with Max5 plan
claude-usage-cli --once                   # Run once and exit
claude-usage-cli --summary                # Show summary only

# Configuration
claude-usage-cli --list-plans             # Show available plans
claude-usage-cli --list-timezones         # Show timezone options
claude-usage-cli --info                   # Show configuration info

# Customization
claude-usage-cli --timezone US/Pacific    # Set timezone
claude-usage-cli --limit-per-5h 60        # Override the 5-hour estimate
claude-usage-cli --weekly-limit 2000      # Track against your own weekly limit
claude-usage-cli --refresh 5              # Set refresh interval
claude-usage-cli --no-color               # Disable colors

Limits

Claude enforces two limits, and neither of them is a daily limit:

Releases up to 1.1.2 displayed a daily limit instead of the weekly one. It did not correspond to anything Claude enforces, and the per-plan numbers behind it were invented. Both are fixed in 1.2.0.

Plans supported

The 5-hour figures are Anthropic's published estimates for average-length chats; real capacity moves with message size, context length, attachments and model, so the output labels them est.. Override with --limit-per-5h.

Weekly limits have no default on purpose. Anthropic publishes them as ranges of model hours, not as a message count, so there is no honest conversion into the message counter this tool keeps. Without --weekly-limit the weekly section still reports real usage — messages, tokens, sessions, burn rate and when your oldest activity rolls off — just without a percentage bar. Supply --weekly-limit N once you know where yours actually bites and you get the bar and a projection.

How It Works

This package reads Claude's conversation logs directly from your local filesystem:

• Location: ~/.config/claude/projects/ (Unix) or %APPDATA%\claude\ (Windows)
• Format: JSONL files containing conversation data
• Processing: Extracts token usage and groups it into 5-hour session windows anchored to your first message (not to fixed slices of the clock)
• Predictions: Analyzes usage patterns to predict future consumption

Zero Dependencies

This package uses only Python's built-in libraries:

• datetime for timezone handling (no pytz needed)
• json for parsing JSONL files
• argparse for CLI interface
• os/sys for system operations

Requirements

• Python 3.7+
• Claude Desktop installed and used at least once
• Access to Claude's local data directory

Development

# Clone repository
git clone https://github.com/jedarden/claude-usage-monitor-cli.git
cd claude-usage-monitor-cli/python

# Install in development mode
pip install -e .

# Run the test suite (stdlib unittest, no dependencies)
python -m unittest discover -s tests -v

# Run directly
python -m claude_monitor.cli --help

License

MIT License - see LICENSE file for details.