transcript-analysis

name	transcript-analysis
description	Analyze Claude Code transcripts — model comparison by branch, test-failure convergence sequences, correction-signal frequency, active-vs-idle duration, subagent-vs-main turn split, PR-to-branch mapping, or per-session review-activity timelines (skill invocations, hook denials, reviewer spawns). For token-cost or cache-efficiency analysis use token-analyzer.py directly.

The toolkit lives at ~/.claude/scripts/transcript-analysis.py. Run it directly from the shell.

Which subcommand to use

Question	Subcommand
Which branches exist? What models were used on each?	buckets
Did a branch converge or thrash during test debugging?	fail-seq --branches <branch>
Did the user express frustration more with one model?	struggle --branches <branch>
How much logged time was active vs idle gaps?	duration --branches <branch>
How much work went through subagents vs the main thread?	subagents --branches <branch>
Map branches to PRs; count per-author review comments	pr-link --repo owner/repo --branches <branch>
Which sessions ran review skills, hit a hook denial, or spawned reviewer agents?	review-trace
Where did a human push back on an AI review's output?	judgment-pair
Is Opus spend doing Sonnet-tier code-read/write in parent sessions?	audit-routing --since 35d --redact
What fraction of Opus code-read turns are clearly dispatchable vs. read-then-edit loops?	audit-routing-shape --since 35d
Pull a random sample of Opus code-read turns for delegation judgment curation	audit-routing-samples --since 35d --sample 50 --seed 1

Reading fail-seq output

Total runs: 12  Failing: 3 (25.0%)  Longest consecutive-failing streak: 2
Sequence: 0 0 5 0 0 0 3 0 0 0 0 0

• Convergent (expected): a spike followed by zeros — the signature of a root-cause fix. The sequence above is convergent.
• Thrashing (flag for review): oscillation like 8 6 9 7 8 with no sustained run of zeros — a model not closing on a fix.
• The longest consecutive-failing streak is the load-bearing metric. A streak of 1–2 is normal (fix lands next run). A streak of 5+ warrants a closer look at the sequence and what was happening between those runs.

Caveats

• The N failed count is a coarse proxy: it matches any N failed in tool output, including pre-existing failures and intentional baseline runs. Treat the sequence view as the primary read; the aggregate rate is corroborating.
• Subagent (isSidechain) turns are excluded from fail-seq and struggle — reviewer, Explore, and code-writer agents are not the debugging surface these subcommands measure.
• Durations from duration are wall-clock dominated by idle gaps. Look at Active(min), not Span(min).
• pr-link requires gh and network access. All other subcommands are local-only and make no writes.
• A model-vs-model comparison is only meaningful when there are multiple all-Opus and all-Sonnet execution branches. One or two branches per model is directional, not a controlled A/B.
• review-trace locates candidate sessions; it does not judge whether a review caught a material issue — that read is qualitative. Use --since/--until (inclusive day bounds) for before/after-a-date analysis and --deny-only to isolate sessions that hit an enforcement hook.
• judgment-pair captures what the human said immediately after a review output. Tool-result turns, isMeta injections, and isCompactSummary records between the review and the user reply are automatically skipped. Use --out to save output to a file for offline curation.
• audit-routing --redact remaps project names to anonymized labels for public reporting — use this flag when posting output to GitHub issues.

Example usage

# Survey all branches
python3 ~/.claude/scripts/transcript-analysis.py buckets

# Check if a branch's debugging loop converged
python3 ~/.claude/scripts/transcript-analysis.py fail-seq --branches feat-TICKET-101

# Compare two branches side by side
python3 ~/.claude/scripts/transcript-analysis.py fail-seq --branches feat-TICKET-101,feat-TICKET-202

# Link branches to PRs and count one author's review comments
python3 ~/.claude/scripts/transcript-analysis.py pr-link \
  --repo owner/repo --branches feat-TICKET-101,feat-TICKET-202 --author alice

# Find sessions that hit an enforcement-hook denial
python3 ~/.claude/scripts/transcript-analysis.py review-trace --deny-only

# Review activity in a date window (e.g. before vs after a skill landed)
python3 ~/.claude/scripts/transcript-analysis.py review-trace --since 2026-01-01 --until 2026-03-31

For narrative case studies and annotated timelines built on top of these metrics, use transcript-narrative.