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.