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.

Sanitize step (2026-09-16). ccusage 20.0.20 silently drops any assistant entry whose usage.iterations[].model is null (ccusage#1710; Claude Code 2.1.269 wrote that on 2026-09-12 and a day of Fable 5.1 cost vanished). The script now mirrors the window's JSONL into $TMPDIR/cfg/projects/ with jq 'del(.message.usage.iterations)' and points ccusage at it via CLAUDE_CONFIG_DIR. ccusage sums top-level usage, so totals are identical on unaffected data and the shim stays harmless after the upstream fix ships.

# 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
• active_seconds v7 = capped active-time. Every message timestamp is collected, sorted, and consecutive gaps summed with each gap capped at IDLE_CAP_SECONDS (900s = 15 min). This is hands-on time — deliberately NOT ended_at − started_at, whose raw span over-counts because a resumed session appends to the same session_id across days (one real session spanned 622h of wall-span, far less active).
• cwd / gitBranch = first non-null occurrence (sticky)
• type=user → increment n_user_msgs; for main sessions, scan tool_result blocks for "agentId: <hex>" and pair the hex back to the subagent_type from the matching Agent tool_use (see "Subagent name attribution" below)
• 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; for name=Agent (subagent dispatch), record (tool_use_id → input.subagent_type) for the agentId lookup above
• type=summary → first one wins, capped at 500 chars
• Files with zero user+assistant msgs are skipped

Subagent name attribution v5

Subagent JSONLs only know their own agentId — the human-readable type (general-purpose, commit-writer, etc.) lives in the parent's Agent tool_use. ingest-sessions.py does a two-pass match:

• Pass 1: while parsing each main session, accumulate two maps — tool_use_id → subagent_type from Agent tool_use blocks, and agent_id → subagent_type by regex-matching "agentId: <hex>" out of the corresponding tool_result. Merge into a global map.
• Pass 2: every subagent JSONL filename is agent-<hex>.jsonl. Strip the prefix, look up the type in the global map, write to conversations.agent_type. Subagents whose parent JSONL was already cleaned off disk stay NULL — the dashboard surfaces the unmatched count in the panel footer.

Steady-state match rate on currently-present JSONLs is ~94%. The unmatched bucket only ever shrinks as older transcripts age out of the 30-day display window.

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 claude 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 ~12 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 13 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) — each family keeps its brand hue (opus → purple, sonnet → cyan, haiku → green), and lightness is ranked by the version embedded in the model id. The newest version present gets the bright brand shade; each older sibling dims one step. A future model (e.g. opus-4-9) slots in by its version with no code change.

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