Claude Code Usage Monitor: a terminal dashboard for token, message and cost limits in 5-hour sessions

What the monitor tracks and who needs it

Claude Code works in session windows, and the README's default plan is built around exactly that: a Custom plan designed for 5-hour Claude Code sessions that watches three numbers. Token usage tracks consumption, message usage counts messages, and cost usage is the one the README calls the most important for long sessions. The monitor draws them in a live terminal view built on the Rich library and warns you as you approach a limit.

The people who need this are the ones whose work stalls when a window runs out: developers who run Claude Code for hours, pair several agents on one account or share a machine between projects. If you use Claude Code for a quick question a few times a day, a live dashboard in a second terminal is more ceremony than the problem deserves.

Where the numbers come from, and how much to trust them

Version 4.0.0 added what the README calls an official-limit trust layer. With --statusline, the monitor captures Claude Code's own rate_limits. When those captures are stale or expired, it falls back to local estimates and labels them as such. Every number it shows or exports carries a provenance label: official, local_estimate, experimental or unknown. That distinction is the most useful thing in the release, because a usage monitor that silently mixes measured and guessed numbers is worse than none: it gives you confidence at exactly the moment the guess is wrong.

The Custom plan computes personalised limits from your own history, analysing all sessions from the last 192 hours, eight days, and building its predictions from that. Input can come from several places: --data-paths, CLAUDE_CONFIG_DIR and WSL discovery can scan multiple directories, and the README notes this happens without merging unrelated accounts into one 5-hour window. Forecasting is reset-aware and freezes when a limit is hit, and weekly percentages are shown only when they come from official data.

Installing Claude Code Usage Monitor with uv, pip or pipx

The README recommends uv because it installs the tool into its own isolated environment, which avoids Python version clashes and the externally-managed-environment error on recent Linux distributions:

uv tool install claude-monitor
claude-monitor

The same command is also available as cmonitor or ccmonitor. With pip the package name is the same:

pip install claude-monitor

If the shell then cannot find claude-monitor, the README's fix is to add ~/.local/bin to PATH. On Ubuntu 23.04 and later, Debian 12 and Fedora 38 it warns against forcing pip past the system Python and suggests uv, a virtual environment or pipx instead:

pipx install claude-monitor

pyproject.toml asks for Python 3.9 or newer and pulls in numpy, pydantic, pydantic-settings, PyYAML, pytz, Rich and wcwidth, so this is a small but not dependency-free install.

Feeding the numbers to other tools

The second half of the 4.0.0 release is for people who want the numbers somewhere other than a terminal. --once prints a single snapshot and exits, --compact prints a short form, and --write-state writes a state file. The README says all three come from one versioned snapshot builder and use automation-friendly exit codes. For machine consumption it recommends asking for JSON:

claude-monitor --once --output json

The README draws a boundary here on purpose: GUIs, tray apps, provider adapters and status bars should consume --write-state or --once --output json instead of scraping the live display. That is the right call. A status bar that parses a Rich terminal layout breaks the next time the layout changes; one that reads a versioned JSON snapshot does not.

The opt-in usage warehouse is the other new piece. It keeps local history that survives Claude's 30-day cleanup, with project, model and day dimensions, and produces CSV and JSON reports. For anyone who has to explain where a month of usage went, that history is the feature that justifies installing the tool.

Limits and rough edges

The monitor can only be as accurate as its inputs. Without a fresh --statusline capture, what you see is a labelled local estimate, and the Custom plan's limits are derived from your own last eight days, so a heavy week raises the ceiling it warns you about. The labels make that visible; they do not make the estimate right.

Platform support is worth checking before relying on it. The package metadata lists Linux and macOS as operating systems, while the Windows classifier line in pyproject.toml is commented out, even though the dependency list includes Windows-only packages and the README mentions WSL discovery. On Windows, WSL is the path the project itself points to. The README also opens a section asking users to help test the release, which is a fair signal that 4.0.0's new protocol and warehouse have seen less real use than the live monitor they grew out of.

Releases, maintenance and the MIT licence

The release list shows a long gap followed by a large jump: v3.0.4 on 2025-07-14 and v3.1.0 on 2025-07-23, then v4.0.0 on 2026-06-27. The last push to the repository was on 2026-07-05. pyproject.toml sets version 4.0.0 and marks the package as production stable, and the README advertises regression coverage for the trust layer, state protocol, warehouse, reports, multi-source paths and timezone edge cases.

The project is MIT licensed. Because the recommended install is uv tool install, upgrading is a matter of reinstalling the tool, and because state files and exports are versioned, anything you built on --write-state should survive an upgrade as long as the snapshot version it reads stays the same. Check the release notes for a new snapshot version before upgrading a machine that feeds a status bar.

Editorial conclusion

Install Claude Code Usage Monitor if you run long Claude Code sessions and keep running into limits without warning. Use uv tool install claude-monitor, turn on --statusline so the numbers come from Claude Code's official rate_limits rather than estimates, and only enable the local warehouse if you want history kept past Claude's 30-day cleanup.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. Maciek-roboblog/Claude-Code-Usage-Monitor on GitHub
4. README
5. Releases