[opensourcedex]

Claude-Code-Usage-Monitor is a free, open source web & product analytics project written in Python and released under MIT. It has 8,712 GitHub stars, 459 forks and 37 open issues, and was last pushed 2 months ago. On this registry it ranks #6 of 25 tracked projects in Web & Product Analytics, with 5 head-to-head comparisons available.

What is Claude-Code-Usage-Monitor?

Claude Code Usage Monitor is a privacy-first terminal and machine-readable usage monitor for people who run Claude Code and need to track token, message, and cost consumption against plan limits. It lives in the Claude Code tooling ecosystem and replaces guesswork about how much of a 5-hour session or weekly allowance remains.

What it is

Claude Code Usage Monitor is a Python package published on PyPI as claude-monitor, distributed under the MIT licence. It pairs a Rich live terminal monitor with an official-limit trust layer, a machine-readable state and export protocol, provenance labels, forecasting, and an opt-in local usage warehouse. It runs locally and is described as a "Claude Usage-Ops companion" for Claude Code.

The concrete problem it solves is visibility into Claude Code consumption. Claude Code enforces token, message, and cost limits, and Claude applies a 30-day cleanup to usage history. This tool surfaces the current state of those limits while the session is running, and its optional warehouse preserves local history beyond that cleanup window. The Custom plan is the default option and is designed for 5-hour Claude Code sessions, tracking token usage, messages usage, and cost usage.

Key capabilities

  • --statusline captures Claude Code's official rate_limits, and stale or expired captures fall back to labeled local estimates.
  • --once, --compact, and --write-state all use one versioned snapshot builder with automation exit codes, giving a single machine-readable protocol.
  • Provenance labels distinguish exported and displayed numbers as official, local_estimate, experimental, or unknown.
  • An opt-in local usage warehouse survives Claude's 30-day cleanup, with project, model, and day dimensions plus CSV and JSON reports.
  • Forecasting and pace features include reset-aware pace, date-context forecasts, official-only weekly percentages, and limit-hit freeze behavior.
  • Multi-source input via --data-paths, CLAUDE_CONFIG_DIR, and WSL discovery scans several directories without merging unrelated accounts into one 5-hour window.
  • Rich UI parity means live output, rich one-shot output, compact output, state files, and exports all use the same snapshot contract.

Who uses it and how

  • Individual Claude Code users watch a live Rich terminal view of token, message, and cost usage during 5-hour sessions and know when a limit is near.
  • Automation authors consume --write-state or --once --output json to drive scripts, with exit codes carrying the status.
  • Developers of GUIs, tray apps, provider adapters, and status bars use the documented external companion boundary rather than parsing terminal output.
  • Users running Claude Code across multiple directories or under WSL point the tool at several data paths while keeping accounts separate.
  • Teams tracking spend over time enable the local warehouse and pull CSV or JSON reports by project, model, or day.

Getting started

Install with uv as the recommended modern route, or with pip install claude-monitor from PyPI. Python 3.9 or later is required.

How it compares

No paid products this project replaces are named in the provided facts, and no comparable tools are named either. It stands alone in this registry.

When to use it — and when not to

Use it if a terminal-first, local, MIT-licensed view of Claude Code limits fits the workflow and Python 3.9 or later is available, with the warehouse optional and stored locally. Do not pick it if a hosted dashboard, shared server-side database, or SMTP-style alerting pipeline is expected, because none of those are described in the facts. The README carries a "Please Help Test This Release!" section for v4.0.0, which indicates the release is still being exercised by users, and 37 open issues remain.

project readme (upstream, from github) — read inline

🎯 Claude Code Usage Monitor

PyPI Version Python Version License: MIT PRs Welcome codecov Mentioned in Awesome Claude Code

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

🚀 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 (Recommended)

Why uv is the best choice:

  • ✅ Creates isolated environments automatically (no system conflicts)
  • ✅ No Python version issues
  • ✅ No "externally-managed-environment" errors
  • ✅ Easy updates and uninstallation
  • ✅ Works on all platforms

The fastest and easiest way to install and use the monitor:

PyPI

Install from PyPI
# Install directly from PyPI with uv (easiest)
uv tool install claude-monitor

# Run from anywhere
claude-monitor  # or cmonitor, ccmonitor for short
Install from Source
# Clone and install from source
git clone https://github.com/Maciek-roboblog/Claude-Code-Usage-Monitor.git
cd Claude-Code-Usage-Monitor
uv tool install .

# Run from anywhere
claude-monitor
First-time uv users

If you don't have uv installed yet, get it with one command:

# On Linux/macOS:
curl -LsSf https://astral.sh/uv/install.sh | sh

# On Windows:
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# After installation, restart your terminal

📦 Installation with pip

# Install from PyPI
pip install claude-monitor

# If claude-monitor command is not found, add ~/.local/bin to PATH:
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc  # or restart your terminal

# Run from anywhere
claude-monitor  # or cmonitor, ccmonitor for short

⚠️ PATH Setup: If you see WARNING: The script claude-monitor is installed in '/home/username/.local/bin' which is not on PATH, follow the export PATH command above.

⚠️ Important: On modern Linux distributions (Ubuntu 23.04+, Debian 12+, Fedora 38+), you may encounter an "externally-managed-environment" error. Instead of using --break-system-packages, we strongly recommend:

  1. Use uv instead (see above) - it's safer and easier
  2. Use a virtual environment - python3 -m venv myenv && source myenv/bin/activate
  3. Use pipx - pipx install claude-monitor

See the Troubleshooting section for detailed solutions.

🛠️ Other Package Managers

pipx (Isolated Environments)
# Install with pipx
pipx install claude-monitor

# Run from anywhere
claude-monitor  # or claude-code-monitor, cmonitor, ccmonitor, ccm for short
conda/mamba
# Install with pip in conda environment
pip install claude-monitor

# Run from anywhere
claude-monitor  # or cmonitor, ccmonitor for short

📖 Usage

Get Help

# Show help information
claude-monitor --help
Available Command-Line Parameters
Parameter Type Default Description
--plan string custom Plan type: pro, max5, max20, team, or custom
--custom-limit-tokens int None Token limit for custom plan (must be > 0)
--view string realtime View type: realtime, daily, monthly, session, entries, sessions, or burn-rate
--output string rich Output format: rich, json, text, or csv
--once flag False Measure once, print a snapshot, and exit
--compact flag False Single-line compact output for status bars
--write-state flag False Write the snapshot to a state file for external tools
--state-file path None State file path for --write-state
--statusline flag False Run as a Claude Code statusline hook and capture official rate_limits
--api flag False Enable the opt-in experimental Anthropic OAuth usage API
--data-paths list [] Claude data directories to scan; repeat or comma-separate values
--warehouse flag False Persist usage entries to the opt-in local warehouse
--warehouse-file path None Usage warehouse file path
--warehouse-retention-days int 365 Days of warehouse records to retain
--timezone string auto Timezone (auto-detected). Examples: UTC, America/New_York, Europe/London
--time-format string auto Time format: 12h, 24h, or auto
--theme string auto Display theme: light, dark, classic, or auto
--refresh-rate int 10 Data refresh rate in seconds (1-60)
--refresh-per-second float 0.75 Display refresh rate in Hz (0.1-20.0)
--reset-hour int None Daily reset hour (0-23)
--date-format string None Date format for daily/m

readme truncated — read the full docs on github

Frequently asked questions

Is Claude-Code-Usage-Monitor free to use?

Claude-Code-Usage-Monitor is open source under the MIT licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does Claude-Code-Usage-Monitor do?

Real-time Claude Code usage monitor with predictions and warnings

What is Claude-Code-Usage-Monitor written in?

Claude-Code-Usage-Monitor is primarily written in Python. Its source is publicly available at https://github.com/Maciek-roboblog/Claude-Code-Usage-Monitor, and it has 8,712 GitHub stars.