Claude-Code-Usage-Monitor

Real-time Claude Code usage monitor with predictions and warnings

What is Claude-Code-Usage-Monitor?

Real-time Claude Code usage monitor with predictions and warnings

Overview of Claude-Code-Usage-Monitor

What it is

Claude-Code-Usage-Monitor is a privacy-first usage monitor for Claude Code. It provides a live terminal monitor with official statusline rate limits, machine-readable state/export output, provenance labels, forecasting, and an opt-in local usage warehouse.

Key features

  • Official-limit trust layer: captures Claude Code's official rate_limits via --statusline; stale or expired captures fall back to labeled local estimates.
  • Machine-readable protocol: --once, --compact, and --write-state 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.

Use cases

Monitoring token, message, and cost usage during long Claude Code sessions. Tracking usage across multiple projects or directories. Generating usage reports for analysis or automation. Integrating with external tools via state files or JSON output.

Getting started

bash# Install from PyPI with uv (recommended)uv tool install claude-monitor# Run from anywhereclaude-monitorAlternatively, install with pip:bashpip install claude-monitorclaude-monitor

License and pricing

License: MIT. Pricing type: open source.

Based on the project's public README and repository metadata.

Add this badge to your README

Featured on YunoDB Badge styles & help

Maintain this project? Show that it is featured on YunoDB.

Markdown[![Featured on YunoDB](https://yunodb.com/badge/maciek-roboblogclaude-code-usage-monitor.svg)](https://yunodb.com/tools/maciek-roboblogclaude-code-usage-monitor?utm_source=github&utm_medium=badge)
HTML<a href="https://yunodb.com/tools/maciek-roboblogclaude-code-usage-monitor?utm_source=github&utm_medium=badge"><img src="https://yunodb.com/badge/maciek-roboblogclaude-code-usage-monitor.svg" alt="Featured on YunoDB" height="20"></a>