Metadata-Version: 2.4
Name: claude-token-dashboard
Version: 0.2.1
Summary: Real-time token usage monitor for Claude Code
Author: Xavi Guardia
License: 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 local usage monitoring for Claude Code and Codex, with Claude utilization pulled from Anthropic's own `/usage` API.

![Weekly budget panel](https://raw.githubusercontent.com/xaviguardia/claudedashboard/main/screenshots/weekly_budget.png)
![Full dashboard](https://raw.githubusercontent.com/xaviguardia/claudedashboard/main/screenshots/dashboard_full.png)
![Live calls](https://raw.githubusercontent.com/xaviguardia/claudedashboard/main/screenshots/live_calls.png)

If you're on Claude Max and also using Codex heavily, this gives you one place to see what you've spent, what is left, and how fast you're burning through each window.

## What it does

- Tracks Claude Code usage from `~/.claude/projects/**/*.jsonl`
- Pulls Claude utilization directly from `https://api.anthropic.com/api/oauth/usage`
- Tracks Codex limits from `~/.codex/sessions/**/*.jsonl` using `token_count` events
- Shows Codex 7-day and 5-hour windows separately from Claude
- Exposes a browser dashboard and a macOS menubar view
- Keeps all processing local

Claude stays on its own calculation path. Codex is added as a separate source, with its own cycle and resets.

## Main views

### Live dashboard

The live dashboard shows:

- Claude weekly utilization, Sonnet utilization, and 5h window
- Codex 7d used, 7d left, 5h used, reset times, and plan type
- A Claude burndown chart
- A separate Codex chart built from local Codex session logs
- Live API calls, session costs, and recent activity

Run it with:

```bash
claude-dashboard live
claude-dashboard live --no-browser --port 8765
```

### Menubar

On macOS, the menubar app shows explicit text for both systems:

- `Claude: xx%`
- `Codex: yy%`

And in the dropdown menu:

- Claude weekly, Sonnet, and 5h
- Codex 7d and 5h
- Claude and Codex reset times
- Pace and recent session cost details

Run it with:

```bash
claude-dashboard menubar
```

Install menubar dependencies with:

```bash
pip install "claude-token-dashboard[menubar]"
```

## Installation

```bash
pip install claude-token-dashboard
```

Or with menubar support:

```bash
pip install "claude-token-dashboard[menubar]"
```

## Data sources

### Claude

Claude Code stores its OAuth token in macOS Keychain under `Claude Code-credentials`. The dashboard reads it locally and calls:

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

That is the same utilization source behind `/usage`.

### Codex

Codex data is read locally from:

```text
~/.codex/sessions/**/*.jsonl
```

The dashboard parses `token_count` events and uses:

- `rate_limits.secondary.used_percent` for the 7-day window
- `rate_limits.primary.used_percent` for the 5-hour window
- `resets_at` for both reset times
- `plan_type` when present

This avoids assuming Codex follows Claude's cycle.

## Commands

```bash
claude-dashboard live
claude-dashboard menubar
claude-dashboard analyze
claude-dashboard burndown
claude-dashboard report
```

## Requirements

- Python 3.9+
- macOS for Claude OAuth lookup through Keychain
- Claude Code installed for Claude usage data
- Codex local sessions available if you want Codex tracking

The browser dashboard works without extra dependencies. The menubar needs `rumps` and `Pillow`.

## Privacy

- All log parsing is local
- Claude project logs are read-only
- Codex session logs are read-only
- The only outbound API call is the Claude usage call to Anthropic using your own local OAuth token

## Billing cycle notes

Claude resets weekly according to Anthropic's Max billing cycle.

Codex is displayed from its own local rate-limit windows and reset timestamps. It is intentionally not forced into Claude's cycle.
