Metadata-Version: 2.4
Name: claude-token-dashboard
Version: 0.1.0
Summary: Real-time token usage monitor for Claude Code
Author: Xavi Guardia
License-Expression: MIT
Project-URL: Homepage, https://github.com/xaviguardia/claudedashboard
Project-URL: Repository, https://github.com/xaviguardia/claudedashboard
Project-URL: Issues, https://github.com/xaviguardia/claudedashboard/issues
Keywords: claude,anthropic,dashboard,token,usage,monitor
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Environment :: MacOS X
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Provides-Extra: menubar
Requires-Dist: rumps>=0.4.0; extra == "menubar"
Requires-Dist: Pillow>=9.0; extra == "menubar"
Provides-Extra: bitbar
Requires-Dist: matplotlib; extra == "bitbar"
Requires-Dist: numpy; extra == "bitbar"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"

# Claude Code Dashboard

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

![Dashboard](screenshots/weekly_budget.png)
![Full Dashboard](screenshots/dashboard_full.png)

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 ⚡

```bash
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

```bash
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

```bash
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

```bash
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.
