token-dashboard-claude-analytics

# Token Dashboard — Claude Code Analytics

> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.

Token Dashboard reads the JSONL transcripts Claude Code writes to `~/.claude/projects/` and turns them into per-prompt cost analytics, tool/file heatmaps, cache analytics, project comparisons, and a rule-based tips engine. Everything runs locally — no data leaves your machine.

## Installation

```bash
git clone https://github.com/nateherkai/token-dashboard.git
cd token-dashboard
python3 cli.py dashboard
```

No `pip install`. No Node.js. No build step. Requires Python 3.8+.

**Windows:**
```bash
git clone https://github.com/nateherkai/token-dashboard.git
cd token-dashboard
py -3 cli.py dashboard
```

## Key CLI Commands

```bash
# Start the full dashboard UI at http://127.0.0.1:8080
python3 cli.py dashboard

# Populate/refresh the SQLite cache, then exit
python3 cli.py scan

# Print today's totals in the terminal
python3 cli.py today

# Print all-time totals in the terminal
python3 cli.py stats

# Show active optimization tips in terminal
python3 cli.py tips

# Dashboard with options
python3 cli.py dashboard --no-open    # don't auto-open browser
python3 cli.py dashboard --no-scan    # skip initial scan, use cached DB only
python3 cli.py dashboard --projects-dir /path/to/projects --db /path/to/cache.db
```

## Configuration

### Environment Variables

```bash
# Change port (default: 8080)
PORT=9000 python3 cli.py dashboard

# Change bind address (WARNING: keep 127.0.0.1 — 0.0.0.0 exposes data on network)
HOST=127.0.0.1 python3 cli.py dashboard

# Custom projects directory
CLAUDE_PROJECTS_DIR=/custom/path python3 cli.py dashboard

# Custom SQLite cache location
TOKEN_DASHBOARD_DB=/custom/path/cache.db python3 cli.py dashboard
```

### Pricing Configuration

Edit `pricing.json` directly to update model prices or add plans:

```json
{
  "models": {
    "claude-opus-4-5": {
      "input": 15.00,
      "output": 75.00,
      "cache_write": 18.75,
      "cache_read": 1.50
    }
  },
  "plans": {
    "api": { "label": "API", "multiplier": 1.0 },
    "pro": { "label": "Pro ($20/mo)", "multiplier": 0.0 },
    "max": { "label": "Max ($100/mo)", "multiplier": 0.0 }
  }
}
```

## Data Sources

Claude Code writes session JSONL files here:

| OS | Path |
|---|---|
| macOS / Linux | `~/.claude/projects/<project-slug>/<session-id>.jsonl` |
| Windows | `C:\Users\<you>\.claude\projects\<project-slug>\<session-id>.jsonl` |

The dashboard only reads these files — never modifies them. It caches results in SQLite at `~/.claude/token-dashboard.db`.

## Dashboard Tabs

| Tab | What it shows |
|---|---|
| **Overview** | All-time totals, daily charts, cost by plan, top tools, recent sessions |
| **Prompts** | Most expensive user prompts ranked by tokens; click to see tool calls and result sizes |
| **Sessions** | Turn-by-turn view with per-turn tokens and tool calls |
| **Projects** | Per-project comparison: tokens, sessions, files touched |
| **Skills** | Most-invoked skills and their token costs |
| **Tips** | Rule-based suggestions (repeated file reads, oversized tool results, low cache-hit rate) |
| **Settings** | Switch between API / Pro / Max pricing plans |

## API Endpoints

The dashboard exposes JSON endpoints at `http://127.0.0.1:8080/api/`:

```bash
# Overview stats
curl http://127.0.0.1:8080/api/overview

# Most expensive prompts
curl http://127.0.0.1:8080/api/prompts

# Session list
curl http://127.0.0.1:8080/api/sessions

# Single session detail
curl http://127.0.0.1:8080/api/sessions/<session-id>

# Project comparison
curl http://127.0.0.1:8080/api/projects

# Optimization tips
curl http://127.0.0.1:8080/api/tips
```

## Real Code Examples

### Scripting Against the SQLite Cache

After running `python3 cli.py scan`, query the cache directly:

```python
import sqlite3
import os

db_path = os.path.expanduser("~/.claude/token-dashboard.db")
conn = sqlite3.connect(db_path)

# Get top 10 most expensive prompts
cursor = conn.execute("""
    SELECT
        project_slug,
        session_id,
        input_tokens,
        output_tokens,
        cache_read_tokens,
        cost_usd,
        substr(user_text, 1, 80) as prompt_preview
    FROM turns
    ORDER BY cost_usd DESC
    LIMIT 10
""")

for row in cursor.fetchall():
    print(f"${row[5]:.4f} | {row[0]} | {row[6]}")

conn.close()
```

### Get Daily Token Totals

```python
import sqlite3
import os

db_path = os.path.expanduser("~/.claude/token-dashboard.db")
conn = sqlite3.connect(db_path)

cursor = conn.execute("""
    SELECT
        date(created_at) as day,
        SUM(input_tokens) as total_input,
        SUM(output_tokens) as total_output,
        SUM(cache_read_tokens) as total_cache_read,
        SUM(cost_usd) as total_cost
    FROM turns
    GROUP BY date(created_at)
    ORDER BY day DESC
    LIMIT 30
""")

for row in cursor.fetchall():
    print(f"{row[0]}: ${row[4]:.4f} ({row[1]} in, {row[2]} out, {row[3]} cached)")

conn.close()
```

### Programmatic Scan via Python

```python
import sys
import os

# Add the project root to path
sys.path.insert(0, '/path/to/token-dashboard')

from token_dashboard.scanner import Scanner

projects_dir = os.path.expanduser("~/.claude/projects")
db_path = os.path.expanduser("~/.claude/token-dashboard.db")

scanner = Scanner(projects_dir=projects_dir, db_path=db_path)
scanner.scan()
print("Scan complete")
```

### Fetch Overview Stats Programmatically

```python
import urllib.request
import json

# Requires dashboard to be running: python3 cli.py dashboard --no-open
with urllib.request.urlopen("http://127.0.0.1:8080/api/overview") as resp:
    data = json.loads(resp.read())

print(f"Total sessions: {data['total_sessions']}")
print(f"Total cost (API): ${data['total_cost_usd']:.2f}")
print(f"Cache hit rate: {data['cache_hit_rate']:.1%}")
```

## Common Patterns

### Reset and Rebuild the Cache

```bash
rm ~/.claude/token-dashboard.db
python3 cli.py scan
```

### Run on a Different Port to Avoid Conflicts

```bash
PORT=9090 python3 cli.py dashboard
```

### Export Tips to File

```bash
python3 cli.py tips > optimization-tips.txt
```

### Automate Daily Stats Logging

```bash
# Add to crontab: 0 9 * * * /path/to/daily-stats.sh
cd /path/to/token-dashboard && python3 cli.py today >> ~/claude-usage-log.txt
```

### Point at a Different Projects Directory

```bash
# If Claude Code projects are in a non-standard location
python3 cli.py dashboard --projects-dir ~/work/.claude/projects
```

## Troubleshooting

| Problem | Solution |
|---|---|
| "No data" / empty charts | Run `python3 cli.py scan` then reload |
| Port 8080 in use | `PORT=9000 python3 cli.py dashboard` |
| Numbers stuck/wrong | Delete `~/.claude/token-dashboard.db`, re-run `python3 cli.py scan` |
| Two instances running | Stop all instances first — they fight over the SQLite DB |
| `python3` not found on Windows | Use `py -3` instead |
| No sessions found | Ensure Claude Code has been used and files exist in `~/.claude/projects/` |

## Architecture Overview

```
cli.py
  └─► token_dashboard/scanner.py   # reads JSONL, dedupes by message.id, writes SQLite
  └─► token_dashboard/server.py    # serves /api/* JSON routes + web/ static files
        └─► web/                   # vanilla JS + vendored ECharts, no build step
pricing.json                       # editable model/plan pricing
~/.claude/token-dashboard.db       # SQLite cache (auto-created)
```

**Deduplication note:** Claude Code writes each assistant response 2–3 times during streaming. The scanner dedupes by `message.id` so tallies match actual API billing — expect lower numbers than tools that sum every raw JSONL row.