Claude Code Usage Dashboard

Overview

Generate an interactive HTML dashboard from Claude Code's local session data. The dashboard shows daily activity, model distribution, project breakdown, hourly patterns, and session details — with live filtering and sortable tables.

Core principles:

1. Script-first. A Python script aggregates all data and produces the HTML. Claude never parses raw JSONL files.
2. Browser-native. The output is a self-contained HTML file with Chart.js charts and client-side filtering. No server needed.
3. Read-only. The script only reads from ~/.claude/. It writes one temp HTML file and opens the browser.

Workflow (MANDATORY)

Step 1: Parse Arguments

Map the user's request to CLI flags:

Convert relative dates to absolute YYYY-MM-DD format. If the user gives a vague range, default to --range 14d.

Step 2: Run the Dashboard Generator

Execute via Bash:

python3 "${CLAUDE_PLUGIN_ROOT}/scripts/generate_dashboard.py" <flags>

The script:

• Reads ~/.claude/stats-cache.json for pre-computed daily data
• Scans ~/.claude/projects/**/*.jsonl for recent session data
• Merges both sources into a complete dataset
• Injects the data into an HTML template
• Writes to /tmp/claude-usage-YYYY-MM-DD.html
• Opens it in the default browser

If the script exits with an error, show the stderr output and stop. Do not attempt manual data parsing.

If the user specifies --range all, warn them it may take 10-30 seconds for large histories before running.

Step 3: Summarize in Conversation

After the dashboard opens, provide a brief text summary (3-5 bullets) so the user gets immediate context without switching to the browser:

• Total messages, sessions, and output tokens for the period
• Busiest and quietest days
• Model split (which model dominated)
• Any notable trend (ramp-up, decline, model shift)

Read the script's stdout to get these numbers — it prints a single JSON line with fields: totalMessages, totalSessions, totalOutputTokens, totalInputTokens, totalCacheReadTokens, busiestDay, quietestDay, topModel, daysActive, startDate, endDate. Parse it and format large token counts readably: "10.7M output tokens", "2.5B cache-read tokens". (Diagnostic messages go to stderr; ignore those.)

Step 4: Offer Follow-Up

End with: "The dashboard is open in your browser. Want a different date range, or should I dig into a specific pattern?"

The user can:

• Ask for a different range → rerun the script
• Ask about specific stats → answer from the data already shown
• Ask to save the report → the HTML file is already saved at the output path

Scope Controls

Common Mistakes