analyzing-claude-sessions

Analyze local Claude Code session transcripts to measure usage patterns, failures, and token costs.

1.6k|168|Updated Dec 16, 2024
One-click install
npx skills add https://github.com/amd/gaia --skill analyzing-claude-sessions-amd
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: analyzing-claude-sessions
Source: https://github.com/amd/gaia/tree/main/.claude/skills/analyzing-claude-sessions
Command: npx skills add https://github.com/amd/gaia --skill analyzing-claude-sessions-amd

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Claude Code records every session as a JSONL transcript, but that raw data is hard to interpret. This Skill turns those transcripts into an evidence-backed report showing what the agent is actually used for, where it fails, and what it costs. ## Core Features & Use Cases - Deterministic extraction pipeline: Runs gaia.factory.harvest modules (scan, report, context, savings) to normalize sessions into traces, intents, and aggregate statistics without sending data anywhere. - Use-case classification: Guides batch labeling of session intent with a consistent taxonomy so reports can break down behavior by workflow type. - Metric rigor: Documents five common analysis pitfalls (subagent scoping, argument hashing, error taxonomy ordering, token carry, harness turns) plus honesty requirements for reporting. - Use Case: A developer wants to know which tools fail most often in their Claude Code sessions and what oversized tool results cost in tokens; the pipeline produces per-tool failure rates and savings estimates in ~/.gaia/cache/factory/. ## Quick Start Analyze my Claude Code session history and produce a report on usage patterns, failure rates, and token costs.

Frequently Asked Questions about analyzing-claude-sessions

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I analyze my Claude Code session history?▼

Run the harvest pipeline: `python -m gaia.factory.harvest.scan` to extract traces, then `report`, `context`, and `savings` modules to generate tables. Claude Code stores transcripts as JSONL under ~/.claude/projects/, and outputs go to ~/.gaia/cache/factory/.

How do I measure Claude Code tool failure rates?▼

The report module computes failure rate per tool from normalized traces, including recovery rate and streak length after failures. Always break failure rates out per tool rather than quoting a corpus-wide average, which hides wide variation.

Can I filter the session scan to a single project?▼

No. The scan covers every Claude Code project on the machine because ~/.claude/projects/ holds one subdirectory per project with no per-project filter. The --root flag relocates the scan but cannot narrow it.

Why do subagent runs get missed in session analysis?▼

Delegated Task/Agent runs get their own transcripts under <session-uuid>/subagents/, which a plain */*.jsonl glob misses entirely. Use iter_traces with Trace.walk() to attach subagents to their parent session.

Is it safe to commit Claude Code analysis reports to a repository?▼

No. Transcripts contain absolute paths, branch names, and anything pasted into prompts, so all derived output must stay in ~/.gaia/cache/factory/. Scrub paths before sharing any report and never commit derived tables.