Open-Source Observability · Maciek-roboblog

Claude-Code-Usage-Monitor

Claude-Code-Usage-Monitor is a Python CLI tool that tracks real-time token, message, and cost consumption for Claude Code sessions. It displays live monitoring in the terminal, predicts usage limits, and optionally archives usage history locally with cost forecasting.

Talk to DEV.co Discuss Implementation

Source: GitHub — github.com/Maciek-roboblog/Claude-Code-Usage-Monitor

8.4k

GitHub stars

431

Forks

Python

Primary language

MIT

License (OSI-approved)

Key facts

Objective fields from the source. Values we can't verify are shown as “Unknown” rather than guessed.

Field	Value
Repository	Maciek-roboblog/Claude-Code-Usage-Monitor
Owner	Maciek-roboblog
Primary language	Python
License	MIT — OSI-approved
Stars	8.4k
Forks	431
Open issues	23
Latest release	v4.0.0 (2026-06-27)
Last updated	2026-07-05
Source	https://github.com/Maciek-roboblog/Claude-Code-Usage-Monitor

What Claude-Code-Usage-Monitor is

MIT-licensed Python 3.9+ tool that captures Claude Code's official rate_limits via statusline integration, implements a machine-readable snapshot protocol with provenance labeling, and provides optional local warehouse storage (CSV/JSON) with reset-aware forecasting and multi-source directory scanning.

Quickstart

Get the Claude-Code-Usage-Monitor source

Clone the repository and explore it locally.

terminalbash

1git clone https://github.com/Maciek-roboblog/Claude-Code-Usage-Monitor.git2cd Claude-Code-Usage-Monitor3# follow the project's README for install & configuration

Need it deployed, integrated, or customized instead? DEV.co ships production installs.

Best use cases

Long-running Claude Code sessions

Monitor token/message consumption during extended 5+ hour coding sessions to avoid hitting rate limits unexpectedly.

Cost optimization for Claude API users

Track per-session costs and forecast daily/weekly spending to manage API budgets and identify expensive usage patterns.

Integration into developer workflows

Use --write-state or --once --output json to export machine-readable snapshots for status bars, GUIs, or external monitoring tools.

Implementation considerations

Installation requires Python 3.9+ and PyPI/uv tooling; modern Linux (Ubuntu 23.04+, Debian 12+) may need virtual environment or uv to avoid externally-managed-environment errors.
Official rate_limits capture via --statusline requires Claude Code to expose limit data in statusline hook; fallback to local estimates if stale or unavailable, with provenance labeling to distinguish confidence.
Opt-in local warehouse persists usage across Claude's 30-day cleanup; retention defaults to 365 days but users must explicitly enable --warehouse flag and manage storage.
Custom plan default analyzes last 192 hours of sessions for adaptive limits; accuracy depends on stable usage patterns and correct timezone/reset-hour configuration.
Multi-source scanning (--data-paths, CLAUDE_CONFIG_DIR, WSL discovery) scans directories independently; manual care required to avoid merging unrelated accounts into single 5-hour window.

When to avoid it — and what to weigh

Need real-time remote monitoring across teams — Tool is local-only; no built-in multi-user dashboard or cloud sync. Team-wide usage tracking requires external aggregation layer.
Require enterprise-grade audit trails — Local warehouse is opt-in and unencrypted; no tamper-evidence, signing, or certified audit log features for compliance scenarios.
Use Python < 3.9 or non-standard environments — Minimum Python 3.9 requirement; PATH setup complications on managed corporate systems or restricted Python deployments.
Need official Anthropic support or SLA — Community-maintained project with no formal support channel; reliance on GitHub issues for bug fixes and feature parity.

License & commercial use

MIT License (OSI-approved, permissive). Allows commercial use, modification, distribution, and private use with attribution and liability disclaimer. No restrictions on proprietary redistribution or SaaS deployment.

MIT license explicitly permits commercial use without restriction. Tool can be bundled, resold, or integrated into commercial products. No license fee or permission required. Verify compliance with any embedded dependencies (Rich, Pydantic, etc.) in your supply chain review.

DEV.co evaluation signals

Editorial assessment — not user reviews. Directional, with an explicit confidence level.

Signal	Assessment
Maintenance	Active
Documentation	Strong
License clarity	Clear
Deployment complexity	Low
DEV.co fit	Good
Assessment confidence	High

Security considerations

Local-only design minimizes remote attack surface. No network calls except opt-in --api flag (experimental OAuth). Warehouse data stored unencrypted in local files; sensitive to local filesystem compromise. Official rate_limits capture assumes Claude Code statusline integrity. No input validation details provided; assume standard Python app risks (e.g., dependency vulnerabilities). Users responsible for protecting local config/warehouse files containing usage metadata.

Alternatives to consider

Anthropic official usage dashboard

Web-based, built by Anthropic, authoritative source; lacks real-time terminal UI and local forecasting, requires browser access and account login.

Custom Python scripts using Claude API

Fully customizable per-team needs; requires development effort, no pre-built UI or warehouse, higher maintenance burden.

Third-party monitoring platforms (e.g., LangSmith, LLMonitor)

Multi-model support and team dashboards; not Claude Code-specific, may have cloud lock-in and subscription costs, different data model.

Software development agency

Build on Claude-Code-Usage-Monitor with DEV.co software developers

Install claude-monitor via uv or pip to track tokens, forecast costs, and avoid rate limit surprises in long Claude Code sessions. Free and open-source.

Talk to DEV.co

Related open-source tools

Surfaced by semantic similarity across the DEV.co open-source index.

TokenTracker claude-devtools Continuous-Claude-v3

Related on DEV.co

Explore the category and the services that help you build with it.

Open-Source Observability AI development API development DevOps Talk to DEV.co

Claude-Code-Usage-Monitor FAQ

Does this tool track usage without local installation?

No. Tool is CLI-based and runs locally. No web-based or remote-hosted version. Optional --write-state can export snapshots for external consumption, but capture still requires local execution.

Can I use this across multiple Claude accounts simultaneously?

Multi-source scanning (--data-paths) can scan multiple directories, but snapshots reflect independent 5-hour windows. Manual aggregation needed for cross-account reporting; not designed for single unified multi-account dashboard.

What happens if Claude Code stops exposing rate_limits?

Tool falls back to local_estimate provenance label. Accuracy depends on past session history and custom plan configuration. Stale or expired official captures are marked clearly so users know confidence level.

Is the local warehouse encrypted or backed up?

Unknown. README states warehouse is opt-in and 30-day cleanup is bypassed, but no details on encryption, backup, or recovery mechanisms. Users responsible for manual backups if needed.

Software developers & web developers for hire

DEV.co is a software development agency delivering custom software development services to companies building on open source. Our software developers and web developers design, integrate, and ship production systems — spanning web development, APIs, AI, data, and cloud. If Claude-Code-Usage-Monitor is part of your open-source observability roadmap, our team can implement, customize, migrate, and maintain it.

Start Monitoring Your Claude Code Usage Today

Install claude-monitor via uv or pip to track tokens, forecast costs, and avoid rate limit surprises in long Claude Code sessions. Free and open-source.

Talk to DEV.co Schedule a Consultation