data-centered / tools / claude usage monitor

Claude Usage Monitor

Track your Claude Code usage against 5-hour and weekly caps. A Python script reads ~/.claude/projects/ and generates a local HTML dashboard with rolling-window gauges, a per-turn scatter, and click-to-mark throttle events you can use to calibrate your personal cap.

Privacy: everything runs locally. The script parses the JSONL transcripts Claude Code already writes to your home directory, computes the rolling windows in memory, and writes a self-contained HTML file you open in your browser. No upload, no account, no telemetry.

What you get

Rolling 5-hour window gauge — total cost, tokens, and turns in the last 5 hours, with a cap % bar.
Rolling 7-day window gauge — same, but for the weekly window.
Throttle markers — click any point in the scatter to mark a rate-limit event. Your markers are saved in your browser and become the cap reference for future readings.
Per-turn scatter — every assistant turn plotted by time × context size, colored by model (opus / sonnet / haiku), with sidechain turns dimmed so they don't dominate.
Hourly rollup — turn counts and 24-hour rolling average context over the lookback window.

About the caps

Anthropic doesn't publish exact numeric thresholds for the 5-hour and weekly limits on Claude Max plans, and the ceilings appear to vary by model mix and plan tier. Rather than hard-coding a wrong number, this tool estimates your cap two ways:

Observed peak (default) — the highest 5h / 7d rolling cost across your history, excluding the current window. A decent proxy if you've been pushing the limits.
Throttle markers (better) — when you actually hit a rate limit, click the point on the chart where it happened. The tool uses the minimum cost across your throttle events as the cap estimate. Markers persist in localStorage.

Run it

Two files: a Python script and an HTML template. Put them in the same folder and run the script. Python 3.9+, stdlib only, no pip install.

claude_usage.py

parser + CLI (stdlib only)

dashboard-template.html

HTML template w/ ECharts

mkdir ~/claude-usage-monitor && cd ~/claude-usage-monitor
curl -O https://data-centered.com/tools/claude-usage-monitor/claude_usage.py
curl -O https://data-centered.com/tools/claude-usage-monitor/dashboard-template.html
python3 claude_usage.py --days 21 --open

That writes claude-usage-dashboard.html in the current directory and opens it in your browser. Re-run any time to refresh — the generator is fast (single-digit seconds for a few weeks of data).

Flags

--days N        lookback window in days (default: 21)
--out PATH      output HTML path (default: ./claude-usage-dashboard.html)
--open          open the generated file in your browser
--json-only     emit JSON instead of HTML (for piping into other tools)

Hand this page to your agent

Paste this URL into Claude Code and say "wire this up for me". The page is structured so an agent can read it once, download both files, run the script, and open the dashboard — no additional instructions needed.

Source & feedback

Built at data-centered.com — short feedback or issue reports via the journal page. The tool is permissively licensed (use it, modify it, ship it in your own stack).