claude-token-dashboard 0.1.0

Real-time token usage monitor for Claude Code

Claude Code Dashboard

Real-time usage monitoring for Claude Code — with actual utilization data straight from Anthropic's API.

If you're on Claude Max and want to know where your weekly budget really stands (not a rough estimate — the exact same number shown by /usage), this is for you.

---

What it does

Claude Code writes every API call to ~/.claude/projects/**/*.jsonl. This dashboard tails those files in real time and layers them with live utilization data from Anthropic's own API, giving you a complete picture of your usage.

Weekly budget panel — pulls seven_day, seven_day_sonnet, and five_hour utilization directly from api.anthropic.com/api/oauth/usage using your existing Claude Code OAuth token (same source as the /usage slash command). Refreshes every 60 seconds.

Burndown chart — week-over-week comparison of your usage pattern, scaled to match Anthropic's real percentages. Useful for spotting if you're burning faster than usual.

Native macOS notifications — fires automatically when you cross 75% or 90% of your weekly budget, and when the 5h rate-limit window is running hot. No third-party apps — just osascript.

Live API call feed — every call as it happens: project, session, tokens, cache hit rate, model.

Real-time activity chart — tokens/min for the last 30 minutes, broken down by input / cache read / output.

---

Tools

claude_token_live.py — Live Dashboard ⚡

python3 claude_token_live.py           # opens http://localhost:8765
python3 claude_token_live.py --port 9000 --no-browser

Starts a local SSE server. Open the browser and get:

• Weekly budget: all-models %, Sonnet-only %, 5h-window % — direct from Anthropic
• Burndown chart: this week vs last week, anchored to real Anthropic utilization
• Today's tokens: stacked input / cache write / cache read / output
• Current session: live token counter for your active Claude Code session
• Live call feed: last 60 API calls with timing, cache efficiency, model used
• Activity chart: tokens/min rolling 30-minute window

Polls log files every 400ms. Anthropic API is called every 60s in a background thread.

Requirements: Python 3.9+ · macOS (uses Keychain for OAuth token) · Claude Code installed

No pip install needed — zero external dependencies.

---

claude_burndown.py — Weekly Burndown Chart

python3 claude_burndown.py             # opens in browser
python3 claude_burndown.py --no-browser > burndown.html

Generates a static HTML chart showing multiple billing cycles overlaid. Each line = one week (Fri 9am → Thu 9am Madrid time). The current week is highlighted in orange.

Useful for understanding your weekly consumption patterns at a glance.

---

claude_token_dashboard.py — Full Historical Dashboard

python3 claude_token_dashboard.py

One-shot HTML report with everything: daily breakdown, hourly heatmap, cache efficiency, model distribution, anomaly detection, top sessions.

---

analyze_tokens.py — CLI Summary

python3 analyze_tokens.py

Text report: totals, per-project, daily breakdown, anomaly alerts, top sessions.

---

How the weekly % works

Claude Code stores its OAuth token in your macOS Keychain under Claude Code-credentials. The live dashboard reads it at runtime and calls:

GET https://api.anthropic.com/api/oauth/usage
Authorization: Bearer <your token>
anthropic-beta: oauth-2025-04-20

The response includes the exact same utilization data that /usage shows interactively. Your token never leaves your machine — the call goes directly from your machine to Anthropic, same as any other Claude Code API call.

---

Data & privacy

• All processing is local
• Log files (~/.claude/projects/) are read-only, never modified
• The only outbound call is to api.anthropic.com with your own OAuth token to fetch your own usage data
• Nothing is sent to third parties

---

Billing cycle

Anthropic resets the weekly budget every Friday at 9:00 AM Madrid time (07:00 UTC in CEST, 08:00 UTC in CET). The dashboard uses this reset time for cycle boundaries.