claude-token-dashboard 0.2.1

Real-time token usage monitor for Claude Code

Claude Code Dashboard

Real-time local usage monitoring for Claude Code and Codex, with Claude utilization pulled from Anthropic's own /usage API.

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:

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:

claude-dashboard menubar

Install menubar dependencies with:

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

Installation

pip install claude-token-dashboard

Or with menubar support:

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:

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:

~/.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

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.