transcript-analyzer

bfreis 的头像作者 bfreis

分析Claude Code会话记录以调试插件、理解上下文使用和跟踪执行流程。

📖 中文导读:分析Claude Code会话记录以调试插件、理解上下文使用和跟踪执行流程。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: transcript-analyzer description: Analyze Claude Code session transcripts to debug plugins, understand context usage, and trace execution flow

Transcript Analyzer Skill

Use this skill when you need to analyze Claude Code session transcripts for:

  • Debugging plugin behavior
  • Understanding context/token usage patterns
  • Tracing tool execution flow
  • Finding sources of context bloat
  • Investigating errors or unexpected behavior

Transcript Location

Claude Code stores session transcripts at:

~/.claude/projects/-PATH-TO-PROJECT/*.jsonl

The path uses dashes instead of slashes. For example:

  • Project: /Users/bfreis/dev/myproject
  • Transcripts: ~/.claude/projects/-Users-bfreis-dev-myproject/*.jsonl

Transcript Structure

Transcripts use JSONL format (one JSON object per line).

Record Types

Type Description
summary Session metadata
file-history-snapshot File change tracking
user User messages (includes tool results)
assistant Assistant messages (includes tool calls)

Message Structure

{
  "type": "user" | "assistant",
  "uuid": "message-uuid",
  "parentUuid": "parent-message-uuid",
  "sessionId": "session-uuid",
  "isSidechain": false,
  "timestamp": "2025-12-06T...",
  "message": {
    "role": "user" | "assistant",
    "content": [...],
    "usage": { "input_tokens": N, "output_tokens": N }
  }
}

Content Block Types

In assistant messages:

  • text - Regular text response
  • tool_use - Tool invocation with .id, .name, .input
  • thinking - Extended thinking blocks

In user messages:

  • text - User input
  • tool_result - Tool output with .tool_use_id, .content

Critical Gotchas

  1. Content is ALWAYS an array - Even single text blocks
  2. Tool result .content can be string OR array - Handle both:
    if .content | type == "array" then
      (.content | map(.text // "") | add)
    else
      .content
    end
    
  3. Use []? not [] - Handles missing fields gracefully
  4. Sub-agents have isSidechain: true - Filter these for main conversation only
  5. parentUuid links threads - Not line order

Using transcript-tool

The skill provides a CLI at scripts/transcript-tool:

# Quick overview
transcript-tool summary session.jsonl

# Find context bloat sources
transcript-tool bloat session.jsonl 15

# Tool usage breakdown
transcript-tool tools session.jsonl

# Trace specific tool
transcript-tool trace-tool session.jsonl Read

# Find errors
transcript-tool errors session.jsonl

# Custom jq query
transcript-tool extract session.jsonl '.type'

Common Analysis Workflows

1. Debug Plugin Behavior

# Find skill invocations
transcript-tool trace-skill session.jsonl plan-generator

# See what tools were used
transcript-tool tools session.jsonl

# Check for errors
transcript-tool errors session.jsonl

2. Investigate Context Bloat

# Find largest tool results
transcript-tool bloat session.jsonl 20

# Message size analysis
transcript-tool messages session.jsonl

# Identify specific large results
transcript-tool extract session.jsonl '
  select(.type == "user") |
  .message.content[]? |
  select(.type == "tool_result") |
  select((.content | tostring | length) > 10000) |
  .tool_use_id
'

3. Trace Execution Flow

# All tool calls in order
transcript-tool extract session.jsonl '
  select(.type == "assistant") |
  .message.content[]? |
  select(.type == "tool_use") |
  "\(.name): \(.input | keys | join(", "))"
'

Raw jq Recipes

For complex analysis, use jq directly:

Count content block types:

jq -r '
  select(.type == "user" or .type == "assistant") |
  .message.content[]? |
  .type
' session.jsonl | sort | uniq -c

Find tool call by ID:

jq -r --arg id "toolu_xxx" '
  select(.type == "assistant") |
  .message.content[]? |
  select(.type == "tool_use" and .id == $id)
' session.jsonl

Get corresponding tool result:

jq -r --arg id "toolu_xxx" '
  select(.type == "user") |
  .message.content[]? |
  select(.type == "tool_result" and .tool_use_id == $id) |
  .content
' session.jsonl

Token usage per message:

jq -r '
  select(.type == "assistant" and .message.usage) |
  "\(.message.usage.input_tokens) in, \(.message.usage.output_tokens) out"
' session.jsonl