Anyone running Claude Code already has Python installed.

Quick Start

No pip install, no virtual environment, no build step.

Windows

git clone https://github.com/phuryn/claude-usage
cd claude-usage
python cli.py dashboard

macOS / Linux

git clone https://github.com/phuryn/claude-usage
cd claude-usage
python3 cli.py dashboard

Usage

On macOS/Linux, use python3 instead of python in 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.

How it works

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 tokens
• message.usage.output_tokens — generated tokens
• message.usage.cache_creation_input_tokens — tokens written to prompt cache
• message.usage.cache_read_input_tokens — tokens served from prompt cache
• message.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).

Cost estimates

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).

Files

| 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, stats, dashboard commands |