Claude Usage Dashboard

A zero-dependency local dashboard that shows, in real time, which Claude model(s) are running on your Mac and how many tokens they're using.

It reads the session logs that Claude Code writes to ~/.claude/projects/**/*.jsonl and serves a live page showing:

• All currently active sessions (model, project, and seconds since the last message — "active" means a message within the last 5 minutes)
• Output / input / cache tokens used today
• A rolling 5-hour total (approximates the rate-limit window), which turns amber then red as it nears a limit you set (see WINDOW_LIMIT below)
• A tokens-per-hour bar chart for the last 24 hours
• Per-model breakdown for today
• An optional API-rate cost estimate (off by default — see below)
• The 12 most recent sessions with totals

Every heading has a hover ⓘ tooltip explaining what the metric means, whether the value is good or bad, and how to influence it. The page auto-refreshes every 3 seconds.

Requirements

• Python 3 (standard library only — no pip installs, no dependencies)
• macOS for the double-click .command launchers; the server itself is plain Python and should run anywhere Claude Code writes its logs
• Claude Code (or Cowork on the same machine) — the dashboard reads its local session logs from ~/.claude

Running

python3 claude_usage_dashboard.py

Then open http://localhost:8437. Press Ctrl+C to stop.

On macOS you can instead double-click Start Dashboard.command — it starts the server (or just opens the page if it's already running) and opens your browser. Stop Dashboard.command stops it.

Options

Variable	Effect
PORT=9000	Serve on a different port
CLAUDE_HOME=/path/to/dir	Read logs from a different location (expects projects/*/*.jsonl inside) — useful for testing with fake data
WINDOW_LIMIT=40000000	Tokens allowed in the rolling 5-hour window before the tile warns (amber at 75%, red at 90%). Default 0 disables the warning — set it to a value you've calibrated, since Anthropic's real rate-limit weighting isn't published locally
SHOW_COST=1	Show the API-rate cost estimate (off by default). Only meaningful if you're billed per token via the API — see below

Cost estimates (off by default)

The cost figures apply Claude API list prices to your token counts. That is not meaningful on a Pro/Max subscription, which is a flat monthly fee rather than per-token billing — so the estimate can read far higher than what you actually pay. It's therefore off by default.

If you are billed per token via the API, set SHOW_COST=1 to reveal an "Est. cost today" tile and a per-model cost column, and edit the PRICES table near the top of claude_usage_dashboard.py (USD per million tokens for input / output / cache-write / cache-read, per model family) to match your rates. Models not listed fall back to DEFAULT_PRICE.

On a subscription, the meaningful budget meter is tokens, not dollars — use the tokens-per-hour chart and the WINDOW_LIMIT warning instead.

Endpoints

• / — the dashboard page
• /data — the raw aggregated data as JSON

Limitations

• Only sessions that run on the local machine are visible. Cloud sessions and Claude Desktop chat conversations don't write local logs, so their usage can't be shown.
• "Last 5h" is an approximation of the rate-limit window; Anthropic doesn't publish the real per-token window weights.
• Token counts are per-message API usage as logged; cache reads dominate the totals and are billed/weighted differently from output tokens.