Pro and Max subscribers get a progress bar. This gives you the full picture.
Claude writes detailed usage logs locally — token counts, models, sessions, projects — regardless of your plan. This dashboard reads those logs and turns them into charts and cost estimates. Works on API, Pro, and Max plans.
This is a fork of phuryn/claude-usage with UI and usability improvements.
Big thanks to @phuryn and The Product Compass Newsletter for the original work. 🙌
- Compact model filter — replaced flat pill buttons (which overflow on wide model lists) with a single dropdown multi-select. Shows "All Models" by default; displays
N / M modelswhen filtered. - Custom favicon — clean icon so the browser tab is easy to spot.
- macOS auto-start — included LaunchAgent plist instructions so the dashboard starts automatically on login.
weekcommand —python3 cli.py weekprints a 7-day summary (per-day + by-model) in the terminal.
Works on API, Pro, and Max plans — Claude writes local usage logs regardless of subscription type. This tool reads those logs and gives you visibility that Anthropic's UI doesn't provide.
Captures usage from:
- Claude Code CLI (
claudecommand in terminal) - VS Code extension (Claude Code sidebar)
- Dispatched Code sessions (sessions routed through Claude Code)
- Claude.ai Cowork sessions — captured from
~/Library/Application Support/Claude/local-agent-mode-sessions/which the Claude desktop app writes locally
Usage is broken down project by project, so you can see which codebases or workflows consume the most tokens.
- Python 3.8+
- No third-party packages — uses only the standard library (
sqlite3,http.server,json,pathlib)
Anyone running Claude Code already has Python installed.
No pip install, no virtual environment, no build step.
git clone https://github.com/aeozturkmen/claude-usage
cd claude-usage
python cli.py dashboard
git clone https://github.com/aeozturkmen/claude-usage
cd claude-usage
python3 cli.py dashboard
On macOS/Linux, use
python3instead ofpythonin all commands below.
# Scan JSONL files and populate the database (~/.claude/usage.db)
python cli.py scan
# Show today's usage summary by model (in terminal)
python cli.py today
# Show the last 7 days (per-day breakdown + by-model totals)
python cli.py week
# Show all-time statistics (in terminal)
python cli.py stats
# Scan + open browser dashboard at http://localhost:8080
python cli.py dashboard
# Custom host and port via environment variables
HOST=0.0.0.0 PORT=9000 python cli.py dashboard
# Scan a custom projects directory
python cli.py scan --projects-dir /path/to/transcripts
The scanner is incremental — it tracks each file's path and modification time, so re-running scan is fast and only processes new or changed files.
By default, the scanner checks both ~/.claude/projects/ and the Xcode Claude integration directory (~/Library/Developer/Xcode/CodingAssistant/ClaudeAgentConfig/projects/), skipping any that don't exist. Use --projects-dir to scan a custom location instead.
Claude Code writes one JSONL file per session to ~/.claude/projects/. Each line is a JSON record; assistant-type records contain:
message.usage.input_tokens— raw prompt tokensmessage.usage.output_tokens— generated tokensmessage.usage.cache_creation_input_tokens— tokens written to prompt cachemessage.usage.cache_read_input_tokens— tokens served from prompt cachemessage.model— the model used (e.g.claude-sonnet-4-6)
scanner.py parses those files and stores the data in a SQLite database at ~/.claude/usage.db.
dashboard.py serves a single-page dashboard on localhost:8080 with Chart.js charts (loaded from CDN). It auto-refreshes every 30 seconds and supports model filtering with bookmarkable URLs. The bind address and port can be overridden with HOST and PORT environment variables (defaults: localhost, 8080).
Costs are calculated using Anthropic API pricing as of April 2026 (claude.com/pricing#api).
Only models whose name contains opus, sonnet, or haiku are included in cost calculations. Local models, unknown models, and any other model names are excluded (shown as n/a).
| Model | Input | Output | Cache Write | Cache Read |
|---|---|---|---|---|
| claude-opus-4-7 | $5.00/MTok | $25.00/MTok | $6.25/MTok | $0.50/MTok |
| claude-opus-4-6 | $5.00/MTok | $25.00/MTok | $6.25/MTok | $0.50/MTok |
| claude-sonnet-4-6 | $3.00/MTok | $15.00/MTok | $3.75/MTok | $0.30/MTok |
| claude-haiku-4-5 | $1.00/MTok | $5.00/MTok | $1.25/MTok | $0.10/MTok |
Note: These are API prices. If you use Claude Code via a Max or Pro subscription, your actual cost structure is different (subscription-based, not per-token).
Create ~/Library/LaunchAgents/com.claudeusage.dashboard.plist:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key>
<string>com.claudeusage.dashboard</string>
<key>ProgramArguments</key>
<array>
<string>/usr/bin/python3</string>
<string>/path/to/claude-usage/cli.py</string>
<string>dashboard</string>
<string>--port</string>
<string>8080</string>
</array>
<key>WorkingDirectory</key>
<string>/path/to/claude-usage</string>
<key>RunAtLoad</key>
<true/>
<key>KeepAlive</key>
<true/>
<key>StandardOutPath</key>
<string>/Users/YOUR_USERNAME/Library/Logs/claudeusage-dashboard.log</string>
<key>StandardErrorPath</key>
<string>/Users/YOUR_USERNAME/Library/Logs/claudeusage-dashboard.err</string>
<key>EnvironmentVariables</key>
<dict>
<key>HOME</key>
<string>/Users/YOUR_USERNAME</string>
<key>PATH</key>
<string>/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
</dict>
</dict>
</plist>Replace /path/to/claude-usage and YOUR_USERNAME with your actual values, then load it:
launchctl load ~/Library/LaunchAgents/com.claudeusage.dashboard.plist| File | Purpose |
|---|---|
scanner.py |
Parses JSONL transcripts, writes to ~/.claude/usage.db |
dashboard.py |
HTTP server + single-page HTML/JS dashboard |
cli.py |
scan, today, week, stats, dashboard commands |