token-dashboard-claude-analytics

Token Dashboard — Claude Code Analytics

Skill by 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

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:

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

Key CLI Commands

# 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

# 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:

{
  "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/:

# 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:

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

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

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

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

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

Run on a Different Port to Avoid Conflicts

PORT=9090 python3 cli.py dashboard

Export Tips to File

python3 cli.py tips > optimization-tips.txt

Automate Daily Stats Logging

# 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

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