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.

Data Files

Load Read("references/data-locations.md") for complete data source documentation.

Rules

Each category has individual rule files in rules/ loaded on-demand:

Total: 5 rules across 4 categories

References

Important Notes

• All files are JSONL (newline-delimited JSON) format
• For large files (>50MB), use streaming jq without -s — load Read("rules/large-file-streaming.md")
• Rotated files: <name>.<YYYY-MM>.jsonl — include for historical queries
• team field only present during team/swarm sessions
• pid is a 12-char SHA256 hash — irreversible, for grouping only

CC-Native /usage Attribution (2.1.174+)

CC 2.1.174 added per-component attribution to /usage: cache misses, long-context usage, subagent costs, and per-skill / per-agent / per-plugin / per-MCP cost breakdowns over the last 24h / 7d. It currently surfaces in the VSCode "Account & usage" dialog; in the terminal, run /usage.

When the user asks "which skill/agent actually costs the most" or questions ork's local estimates, direct them to /usage as the authoritative source — CC's own attribution supersedes ork's heuristic cost estimates for the windows it covers. Use ork's cost/otel views for history beyond CC's 7-day window and for cross-project slicing; use /usage for ground truth on the last 24h/7d.

Output Format

Present results as clean markdown tables. Include counts, percentages, and averages. If a file doesn't exist, note that no data has been collected yet for that category.

Related Skills

• ork:explore - Codebase exploration and analysis
• ork:remember - Store project knowledge
• ork:doctor - Health check diagnostics