Analytics

Cross-Project Analytics

Query local analytics data from ~/.claude/analytics/. All data is local-only, privacy-safe (hashed project IDs, no PII).

Answer usage questions from the local files, never from guesswork: agent usage (which agents and how often — not which model, see the caveats) lives in ~/.claude/analytics/agent-usage.jsonl; hook performance and failures live in ~/.claude/analytics/hook-timing.jsonl; token and cost totals live in ~/.claude/stats-cache.json. Query them with jq one-liners (below) and present real counts, not pointers to dashboards.

Subcommands

Parse the user's argument to determine which report to show. If no argument provided, use AskUserQuestion to let them pick.

Quick Start Example

# Top agents by spawn frequency. Excludes phantom rows (see caveat below).
jq -s 'map(select(.agent != "unknown")) | group_by(.agent) | map({agent: .[0].agent, count: length}) | sort_by(-.count)' ~/.claude/analytics/agent-usage.jsonl

# Cost per model: input + output token counts (multiply by per-model pricing;
# count cache-read tokens separately — prompt-cache hits are ~90% cheaper, so
# cache savings materially lower the real total)
jq '.modelUsage | to_entries | map({model: .key, input: .value.inputTokens, output: .value.outputTokens, cacheRead: .value.cacheReadInputTokens})' ~/.claude/stats-cache.json

# Slowest hooks by average duration, and failure rate as a percentage
jq -s 'group_by(.hook) | map({hook: .[0].hook, avg_ms: (map(.duration_ms) | add / length), fail_pct: (100 * (map(select(.ok != true)) | length) / length)}) | sort_by(-.avg_ms)' ~/.claude/analytics/hook-timing.jsonl

Quick Subcommand Guide

agents, models, skills, hooks, teams, summary — Run the jq query from Read("references/jq-queries.md") for the matching subcommand. Present results as a markdown table.

session — Follow the 4-step process in Read("references/session-replay.md"): locate session file, resolve reference (latest/partial/full ID), parse JSONL, present timeline.

cost — Apply model-specific pricing from Read("references/cost-estimation.md") to CC's stats-cache.json. Show per-model breakdown, totals, and cache savings. On CC >= 2.1.174, cross-check against CC-native /usage per-component attribution (see 'CC-Native /usage Attribution' below).

trends — Follow the 4-step process in Read("references/trends-analysis.md"): daily activity, model delegation, peak hours, all-time stats.

summary — Run all subcommands and present a unified view: total sessions, top 5 agents, top 5 skills, team activity, unique projects. If ~/.claude/otel/*.jsonl exists with non-empty content, append the three OTEL panels from otel-fields.md; otherwise omit them (do not render empty panels).

otel — Render the OTEL panels: 3 from CC 2.1.117 (top slash commands user-vs-model, per-effort cost, effort-vs-success correlation), 3 from CC 2.1.119 (oversized inputs, pre/post latency, see otel-fields.md), 1 from CC 2.1.122 (most-mentioned @ targets), and 1 from CC 2.1.126 (skill activation by trigger type). See Read("references/otel-fields.md") for queries, graceful-fallback rules, and panel semantics. Each panel falls back cleanly to "no OTEL data available (upgrade to CC ≥ X)" when its specific file is absent or empty — render only the panels with data.

Data-Quality Caveats — read before reporting any number

Two measured defects in agent-usage.jsonl change what this file can honestly answer. Verified against 11,249 real rows on 2026-07-20.

1. Four of eight fields are dead for 100% of rows (#3034). model is the literal string "unknown" on every row, agent_name is null on every row, output_len is 0 on every row, and duration_ms is absent entirely. Only ts, pid, agent, and success carry signal. Do NOT report model delegation, agent duration, or output size from this file — grouping by .model returns one unknown bucket, not a breakdown. If asked, say the data is unavailable and cite #3034 rather than presenting a single-bucket result as if it were an answer.

2. ~38% of rows are phantom events, not spawns (#3035). Rows with agent == "unknown" have no SubagentStart, no readable transcript, and their agent ids appear nowhere in Claude Code's own session data. They are an inflated denominator: any activation ratio computed over the full file is wrong. Filter select(.agent != "unknown") before computing any share, percentage, or ranking. A specialist-vs-generic split over the raw file understates specialists by roughly a third.

Both are writer-side defects, not query bugs — a better jq expression cannot recover the missing signal.