Skip to main content
skill CX Codex

analytics · yonatangross — Claude Code skill: what it does, how to install

analytics queries local Claude Code logs to report agent usage, hook latency, and token expenses. Runs whenever you inspect session costs or runtime bottlenecks.

MIT 210 installs ★ 305 updated 2026-11-07

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add yonatangross/orchestkit --skill analytics -a claude-code
Open on GitHub

What analytics does

The skill inspects local telemetry stored under ~/.claude/analytics/ and token tallies inside ~/.claude/stats-cache.json. Queries execute via jq one-liners directly in your shell, rendering summaries as clean Markdown tables. Project IDs remain hashed to protect privacy without pushing telemetry to third-party dashboards.

Dedicated subcommands break data down into specific perspectives: agent call counts, slow hooks, session replays, and estimated model costs factoring in prompt cache discounts. If OpenTelemetry files exist in the environment, it renders supplemental telemetry panels.

Execution relies on Bash and the jq CLI binary. In agent-usage.jsonl, roughly 38% of records represent phantom events with unknown agent names, which the tool filters out to prevent skewed ratios.

What it helps with

  • calculate token spending factoring in prompt cache discounts
  • identify slowest hooks and calculate failure percentages
  • inspect invocation counts for subagents and skills
  • replay session timelines to trace tool calls and delays

Example prompts for the agent

  • Run analytics summary to view overall agent and skill activity
  • Calculate token expenses across all models using analytics cost
  • Find the slowest hooks and error rates with analytics hooks

How to install analytics

1Skills CLI (Vercel)

npx skills add yonatangross/orchestkit --skill analytics -a claude-code

2Manually: put the files in place

~/.claude/skills/analytics/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/analytics/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about analytics

How to install analytics in Claude Code?

Run npx skills add yonatangross/orchestkit --skill analytics -a claude-code in your terminal.

What does the analytics skill do?

It parses local session files and metrics caches to report token costs, hook runtimes, and subagent activity without transmitting logs externally.

What system dependencies are required?

You need jq installed in your path because the skill processes local JSONL metrics using command-line filters.

Source text

SKILL.md · MIT
---
name: analytics
license: MIT
compatibility: "Claude Code 2.1.277+."
description: "Local OrchestKit usage analytics: agent and skill frequency, hook timing, session replay, cost estimates, model delegation trends. Use when reviewing usage, performance or costs."
argument-hint: "[agents|models|skills|hooks|teams|session|cost|trends|summary]"
context: inherit
user-invocable: false
allowed-tools: "Bash Read Grep Glob AskUserQuestion"
effort: low
model: haiku
metadata:
  category: document-asset-creation
  version: "2.1.0"
  author: "OrchestKit"
  complexity: "low"
  tags: "analytics, metrics, usage, teams, agents, skills, hooks, data-visualization, dashboard, recharts, charts, widgets, session, cost, tokens, model-delegation"
---

# 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.

| Subcommand | Description | Data Source | Reference |
|------------|-------------|-------------|-----------|
| `agents` | Top agents by frequency and success rate (duration/model unavailable — #3034) | `agent-usage.jsonl` | `references/jq-queries.md` |
| `models` | Model delegation from **token totals** in `stats-cache.json`. Per-spawn attribution is unavailable (#3034) | `stats-cache.json` | `references/jq-queries.md` |
| `skills` | Top skills by invocation count | `skill-usage.jsonl` | `references/jq-queries.md` |
| `hooks` | Slowest hooks and failure rates | `hook-timing.jsonl` | `references/jq-queries.md` |
| `teams` | Team spawn counts, idle time, task completions | `team-activity.jsonl` | `references/jq-queries.md` |
| `session` | Replay a session timeline with tools, tokens, timing | CC session JSONL | `references/session-replay.md` |
| `cost` | Token cost estimation with cache savings | `stats-cache.json` | `references/cost-estimation.md` |
| `trends` | Daily activity, model delegation, peak hours | `stats-cache.json` | `references/trends-analysis.md` |
| `summary` | Unified view of all categories | All files | `references/jq-queries.md` |
| `otel` | CC 2.1.117 + 2.1.122 + 2.1.126 OTEL enrichments: top slash commands (user vs model), per-effort cost, effort-vs-success correlation, skill activation by trigger type, most-mentioned `@` targets | `~/.claude/otel/*.jsonl`, or user-named Loki + Prometheus endpoints after schema discovery | `references/otel-fields.md`, `references/otel-gateway-source.md` |

### Quick Start Example

```bash
# 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.

| File | Contents |
|------|----------|
| `agent-usage.jsonl` | Agent spawns — usable fields are `ts`, `pid`, `agent`, `success` only. `model`/`agent_name`/`output_len`/`duration_ms` are dead (#3034) and ~38% of rows are phantoms (#3035) |
| `skill-usage.jsonl` | Skill invocations |
| `hook-timing.jsonl` | Hook execution timing and failure rates |
| `session-summary.jsonl` | Session end summaries |
| `task-usage.jsonl` | Task completions |
| `team-activity.jsonl` | Team spawns and idle events |

## Rules

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

| Category | Rule | Impact | Key Pattern |
|----------|------|--------|-------------|
| Data Integrity | `rules/data-privacy.md` | CRITICAL | Hash project IDs, never log PII, local-only |
| Cost & Tokens | `rules/cost-calculation.md` | HIGH | Separate pricing per token type, cache savings |
| Performance | `rules/large-file-streaming.md` | HIGH | Streaming jq for >50MB, rotation-aware queries |
| Visualization | `rules/visualization-recharts.md` | HIGH | Recharts charts, ResponsiveContainer, tooltips |
| Visualization | `rules/visualization-dashboards.md` | HIGH | Dashboard grids, stat cards, widget registry |

**Total: 5 rules across 4 categories**

## References

| Reference | Contents |
|-----------|----------|
| `references/jq-queries.md` | Ready-to-run jq queries for all JSONL subcommands |
| `references/session-replay.md` | Session JSONL parsing, timeline extraction, presentation |
| `references/cost-estimation.md` | Pricing table, cost formula, daily cost queries |
| `references/trends-analysis.md` | Daily activity, model delegation, peak hours queries |
| `references/data-locations.md` | All data sources, file formats, CC session structure |
| `references/otel-fields.md` | CC 2.1.117 OTEL fields (command_name, command_source, effort), queries, and dashboard panels |

## 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
- `ork:prompt-focus` - Where the user's own attention went, from their prompts (the user's own prompts, not tool telemetry)

© OrchestKit · MIT · yonatangross/orchestkit

Similar skills

All skills for Agent setup: memory, context, orchestration →

analytics by other authors comes first.

analytics coreyhaines31 analytics — a skill for Claude Code that structures tracking plans and audits metric calculations. Standardizes event naming across GA4, GTM, Mixpanel, and PostHog. CX Codex +1 97,200installs analytics apolloio analytics — a skill for Claude Code and other AI editors turns sales questions into Apollo tables. Ask about emails, calls, meetings or deals and get real numbers back instead of raw API output. CX Codex +1 636installs analytics Microsoft analytics is a Claude Code skill that routes Process Mining queries, shows process and event/variant metrics, and loads a specialist skill for deeper analysis. CX Codex +1 ★ 1,167repo stars analytics-advisor Son Nguyen analytics-advisor — a subagent that pulls numbers off the Agent Monitor dashboard and explains where your Claude session budget goes. CX Codex ★ 1,198repo stars ccam-analytics Son Nguyen ccam-analytics tracks Claude Code sessions via Agent Monitor, providing token breakdowns, cost tracking, usage trends, and productivity scores. CX Codex ★ 1,198repo stars google-analytics acedatacloud Pulls GA4 reports and property lists through the Google Analytics APIs, using curl and jq from the agent's shell. CX Codex +1 177installs lean-analytics wondelai A skill for Claude Code and Codex designed to audit dashboards and pick startup KPIs via the Lean Analytics framework. Identifies actionable ratios and flags misleading vanity totals. CX Codex +1 3,500installs cargo-analytics getcargo The cargo-analytics Claude Code skill measures Cargo run results and exports data as CSV or JSON. Use it to count errors or retrieve a run’s output. CX Codex +1 11,600installs openrouter-analytics-query OpenRouterTeam openrouter-analytics-query — a skill for building and running queries against the OpenRouter analytics API. Use it to pull metrics on model usage, group results by dimensions, and filter by time, model, or other parameters. CX Codex +1 355installs

From the same set86

The whole set →
api-design api-design establishes design standards for REST, GraphQL, and gRPC contracts when editing endpoints or OpenAPI files. Triggers on route definitions and schema changes. CX Codex +1 211installs assess The assess skill rates code or design decisions 0-10 across seven dimensions: correctness, readability, complexity, performance, security, maintainability and compliance. CX Codex +1 211installs verify verify is a skill that checks whether work is ready to merge by running tests, security and type checks, then assigns a 0–10 score. CX Codex +1 210installs commit Creates Conventional Commits with scope detection, Co-Authored-By trailers and pre-commit checks; blocks secrets and generated files. Runs on commit or “save my changes”. CX Codex +1 210installs create-pr create-pr — a skill that opens a GitHub pull request after running tests, linter, types, and security checks. Triggers on explicit invocation; plain gh pr create stays a command. CX Codex +1 209installs audit-full audit-full audits an entire codebase for security, architecture, and dependency issues in one pass, then ranks findings by severity. It fits release checks and security reviews. CX Codex +1 208installs implement The implement skill builds a new feature in parallel: backend, frontend, tests and security checks in separate worktrees. Triggered by implement [description] — designs the architecture, splits work across subagents, runs tests. CX Codex +1 206installs demo-producer demo-producer — a skill for Claude Code automates showcase video creation for skills, CLIs, and code. Handles everything from terminal recording via VHS to video composition in Remotion. CX Codex +1 196installs

Project sponsors

Companies that keep this analytics open