claude-stats

CLI commands

Fish function at ~/.config/fish/functions/claude-stats.fish. All read-only against ~/Documents/claude-stats/claude.duckdb unless noted. Four subcommands plus help.

The display surface interactive

Maintenance non-display

How ingest-daily.sh works

Pulls per-day cost & token totals from ccusage (Anthropic's open-source usage CLI), reshapes via jq, UPSERTs into two tables: daily_usage (date × model) and project_daily_usage (project × date × model, via --instances --breakdown). Runs nightly at 02:00 via systemd timer.

# ccusage emits nested JSON per day with .modelBreakdowns[]
# jq flattens to one CSV row per (day, model)
.daily[] as $d
| $d.modelBreakdowns[]
| [
    $d.date,
    .modelName,
    (.inputTokens // 0),
    (.outputTokens // 0),
    (.cacheCreationTokens // 0),
    (.cacheReadTokens // 0),
    (.cost // 0)
  ]
| @csv

CREATE OR REPLACE TEMP TABLE staging AS
SELECT * FROM read_csv('$CSV',
  header=false,
  columns={
    'date': 'DATE',
    'model': 'VARCHAR',
    'input_tokens': 'BIGINT',
    ...
  });

INSERT OR REPLACE INTO daily_usage
SELECT date, model, input_tokens, output_tokens,
       cache_creation_tokens, cache_read_tokens, cost,
       CURRENT_TIMESTAMP
FROM staging;

How ingest-sessions.py works

Walks every .jsonl conversation transcript under ~/.claude/projects/, parses message events & tool-use blocks, then UPSERTs into three tables. Per-project cost now lives in project_daily_usage (populated by ingest-daily.sh); this script no longer touches cost.

Path classification

Two JSONL shapes exist under ~/.claude/projects/<project>/:

• Main: <project>/<uuid>.jsonl → kind = 'main'
• Subagent: <project>/<parent_uuid>/subagents/<agent-id>.jsonl → kind = 'subagent' with parent_session_id set

Per-line parse

Each JSONL line is a typed event. The parser tracks:

• started_at / ended_at = min/max timestamp across lines
• cwd / gitBranch = first non-null occurrence (sticky)
• type=user → increment n_user_msgs
• type=assistant → increment n_assistant_msgs; track peak context (input + cache_create + cache_read); count tool-use blocks in content[]; for blocks with name=Skill, also count input.skill into a per-session skill tally
• type=summary → first one wins, capped at 500 chars
• Files with zero user+assistant msgs are skipped

Storage

• conversations — one row per JSONL (PK: session_id = filename stem)
• conversation_tool_usage — one row per (session, tool); aggregated call_count
• conversation_skill_usage — one row per (session, skill); skill names are <plugin>:<name> for plugin-namespaced skills, or bare <name> for personal skills
• project_daily_usage (v4) — per-(project_path, date, model) cost from ccusage daily --instances --breakdown --json, populated alongside daily_usage in the same ingest-daily.sh run. Same 8-day rolling-rewrite discipline: rows older than 8 days are immutable. Sums to daily_usage exactly for any (date, model) where ccusage could see the JSONLs at ingest time. The dashboard's "Top projects" panel windows over this table.

How build-dashboard.sh works

Self-contained HTML generator. Runs ~9 DuckDB queries, embeds the results as a JSON literal in the page, ships Plotly via CDN, and lets the browser render everything client-side. No build step, no server.

The 10 queries embedded as DATA

AMOLED theme

Color tokens used by both the dashboard and this docs site (single source of truth in docs/_styles.css):

--bg:        #000000   /* true black for OLED panels */
--panel:     #0a0a0a   /* card background */
--primary:   #a78bfa   /* electric purple — opus, accents */
--secondary: #22d3ee   /* cyan — sonnet, secondary accent */
--good:      #22c55e   /* green — haiku, healthy state */
--warn:      #f59e0b   /* amber */
--bad:       #ef4444   /* red — compaction risk */
--pink:      #ec4899   /* fourth distinct */

Stable per-model coloring is done in JS via colorForModel(m) — opus → primary, sonnet → secondary, haiku → good, others → warn.

Schema

Five tables. Source-of-truth at ~/Documents/pulse/claude-stats/schema.sql. Re-applied idempotently on each install.sh run (uses CREATE TABLE IF NOT EXISTS).

daily_usage populated by ingest-daily.sh

project_daily_usage populated by ingest-daily.sh (--instances)

conversations one row per JSONL transcript

conversation_tool_usage

conversation_skill_usage