analyzing-cc-sessions

name	analyzing-cc-sessions
description	Use when analyzing Claude Code raw session logs, parsing JSONL transcripts, investigating agent behavior, extracting metrics from session data, debugging subagent dispatches, or building session analysis tools. Triggers on session IDs, JSONL paths, ~/.claude/projects references, or requests to understand what happened in a CC session.

Analyzing Claude Code Raw Sessions

Overview

Claude Code stores every conversation as JSONL transcripts — one JSON object per line. Main sessions track the full human-agent dialogue. Subagent dispatches get their own JSONL files. Large tool outputs are persisted separately as text files.

Core principle: Main session = orchestration log. Subagent files = the real work. Tool-results = the large payloads. Most analysis targets subagent behavior, not the main session.

When to Use

• Analyzing what happened in a CC session (efficiency, behavior, errors)
• Parsing subagent logs for tool call patterns or waste
• Extracting metrics (tokens, duration, tool counts, findings)
• Debugging why a subagent failed or produced poor results
• Building or maintaining session analysis scripts
• Correlating main session dispatches with subagent execution

Before You Start

Your goal	Start here
Understand what happened in a session	Main session JSONL → find Agent tool calls → follow to subagent files
Analyze a specific subagent's behavior	Subagent JSONL directly ({session}/subagents/agent-{id}.jsonl)
Extract metrics across sessions	Existing analysis scripts (see below)
Debug why a subagent failed	Subagent JSONL → last assistant entry → check for errors in preceding tool results
Correlate main session ↔ subagent	Main session Agent tool_use → progress entries with agentId → subagent file

Session Data Locations

Project Directory

Sessions are stored per-project at:

~/.claude/projects/{path-hash}/

The {path-hash} is the absolute project path with / replaced by -, leading - stripped:

/Users/jane/projects/my-app
→ -Users-jane-projects-my-app

Directory Structure

~/.claude/projects/{path-hash}/
├── {session-uuid}.jsonl              # Main session transcript
├── {session-uuid}/
│   ├── subagents/
│   │   ├── agent-{id}.jsonl          # One per dispatched subagent
│   │   └── agent-acompact-{id}.jsonl # System compaction agents (SKIP these)
│   └── tool-results/
│       └── {tool_use_id}.txt         # Large tool outputs persisted here

Resolving a Project Directory

from pathlib import Path

def resolve_project_dir(project_path: str) -> Path:
    """Convert project path to ~/.claude/projects/ hash directory."""
    absolute = Path(project_path).resolve()
    hash_name = str(absolute).replace("/", "-").lstrip("-")
    return Path.home() / ".claude" / "projects" / hash_name

Finding Recent Sessions

Sessions are .jsonl files sorted by modification time. Only sessions with a {session-uuid}/subagents/ subdirectory contain subagent data worth analyzing.

from pathlib import Path

def find_sessions_with_subagents(project_dir: Path, limit: int = 10):
    """Find recent sessions that have subagent dispatches."""
    candidates = []
    for jsonl in project_dir.glob("*.jsonl"):
        subagents_dir = project_dir / jsonl.stem / "subagents"
        if subagents_dir.is_dir() and any(subagents_dir.iterdir()):
            candidates.append((jsonl.stat().st_mtime, jsonl.stem))
    candidates.sort(reverse=True)
    return [sid for _, sid in candidates[:limit]]

Main Session JSONL Structure

Each line is a JSON object with a type field. There are 5 entry types:

Entry Types

Type	Purpose	Frequency	Analysis Value
assistant	Model responses (text, tool calls, thinking)	~15-20%	HIGH — tool sequences, reasoning
user	User messages + tool results	~10-15%	HIGH — tool results, user corrections
progress	Streaming progress (agent, bash, hooks)	~60-70%	LOW — mostly noise, but agent_progress has agentId
system	Turn duration, metadata	~1-2%	LOW — timing data
file-history-snapshot	File backup snapshots	~2-3%	SKIP

Common Fields (All Entry Types)

{
  "type": "assistant|user|progress|system|file-history-snapshot",
  "uuid": "unique-entry-id",
  "parentUuid": "parent-entry-id",
  "timestamp": "2026-03-01T14:30:00.000Z",
  "sessionId": "session-uuid",
  "cwd": "/current/working/directory",
  "gitBranch": "feature/branch-name",
  "version": "1.0.43"
}

Assistant Entries

{
  "type": "assistant",
  "message": {
    "role": "assistant",
    "model": "claude-opus-4-6",
    "content": [
      {"type": "thinking", "text": "...reasoning..."},
      {"type": "text", "text": "...visible response..."},
      {"type": "tool_use", "id": "toolu_01ABC...", "name": "Read", "input": {"file_path": "/path"}}
    ],
    "usage": {"input_tokens": 1234, "output_tokens": 567},
    "stop_reason": "end_turn|tool_use"
  }
}

Content block types in assistant messages:

• thinking — extended thinking (main session only — see Gotchas). Field name is thinking, not text. Content is redacted (empty string + signature field for verification).
• text — visible text response
• tool_use — tool invocation with id, name, input

User Entries

User entries carry two kinds of content:

1. Human messages — content is a plain string:

{
  "type": "user",
  "message": {
    "role": "user",
    "content": "Fix the authentication bug"
  }
}

2. Tool results — content is a list of tool_result blocks:

{
  "type": "user",
  "message": {
    "role": "user",
    "content": [
      {
        "type": "tool_result",
        "tool_use_id": "toolu_01ABC...",
        "content": "file contents here...",
        "is_error": false
      }
    ]
  }
}

Key: Match tool_result.tool_use_id to tool_use.id in the preceding assistant message to pair calls with results.

Progress Entries

High-volume, mostly noise. Three subtypes via data.type:

data.type	Contains	When to Use
agent_progress	agentId, streaming messages	Correlating which agentId maps to which subagent file
bash_progress	Streaming bash output	Rarely useful (final output is in tool_result)
hook_progress	Hook execution events	Debugging hook failures

Tool Results Persistence

When a tool result exceeds ~30KB, CC persists it to tool-results/{tool_use_id}.txt instead of embedding it inline. The tool_result content in the JSONL will reference this file.

This matters for analysis because: Bootstrap outputs, large file reads, and git command results often exceed this threshold. You'll see the tool_result in the JSONL but the actual content is in the separate file.

Subagent JSONL Structure

Subagent files at {session}/subagents/agent-{id}.jsonl have a simpler structure than main sessions:

• No progress entries — just alternating user and assistant messages
• First line = dispatch prompt (the user message with the task)
• Subsequent lines = alternating assistant tool calls and user tool results
• Similar content block format as main session (tool_use, tool_result, text) but no thinking blocks — extended thinking is stripped from subagent JSONL even when it occurs (see Gotchas)

Line 0: user    → dispatch prompt (contains the full task/instructions)
Line 1: assistant → first response (may include text + tool_use)
Line 2: user    → tool results
Line 3: assistant → next response
...
Line N: assistant → final response (text with completion message)

Selecting Task-Relevant Agents

Process only files matching agent-{id}.jsonl where {id} is a numeric or UUID identifier. Files named agent-acompact-*.jsonl are internal compaction agents — exclude them:

def is_task_agent(filename: str) -> bool:
    """Return True for task-relevant agent files, False for system agents."""
    return filename.startswith("agent-") and "-acompact-" not in filename

Identifying Agent Type

The dispatch prompt (first user message) usually contains the agent type:

def infer_agent_type(prompt: str) -> str:
    """Infer agent type from dispatch prompt keywords."""
    patterns = {
        "security-reviewer": ["security review", "security issues"],
        "patterns-reviewer": ["pattern consistency", "codebase consistency"],
        "code-reviewer": ["code quality", "general review"],
        "Explore": ["explore", "find files", "search code"],
        "Plan": ["plan", "design", "architect"],
    }
    prompt_lower = prompt.lower()
    for agent, keywords in patterns.items():
        if any(kw in prompt_lower for kw in keywords):
            return agent
    return "unknown"

For reviewer agents dispatched via bootstrap.py, the prompt always contains --agent {agent-name}.

Correlating Main Session ↔ Subagent

In the main session, an Agent tool call creates a subagent. The correlation chain:

1. Main session: tool_use with name: "Agent" → has an id (tool_use_id)
2. Main session: progress entries with data.type: "agent_progress" → contain data.agentId
3. Subagent file: named agent-{agentId}.jsonl
4. Main session: tool_result with matching tool_use_id → contains the agent's final output

Parsing Recipes

Expect imperfect data. Session JSONL files regularly contain empty lines, truncated entries, and content fields that switch between string and list types within the same file. Every parser must handle json.JSONDecodeError per line (skip and continue), type-check content before iterating (string vs list), and treat missing fields as absent rather than raising errors.

Extract All Tool Calls from a Subagent

import json

def extract_tool_calls(filepath: str) -> list[dict]:
    """Extract ordered list of tool calls from a subagent JSONL."""
    calls = []
    with open(filepath) as f:
        for line in f:
            entry = json.loads(line.strip())
            msg = entry.get("message", {})
            if not isinstance(msg, dict) or msg.get("role") != "assistant":
                continue
            content = msg.get("content", [])
            if not isinstance(content, list):
                continue
            for block in content:
                if isinstance(block, dict) and block.get("type") == "tool_use":
                    calls.append({
                        "name": block.get("name"),
                        "id": block.get("id"),
                        "input": block.get("input", {}),
                    })
    return calls

Categorize Bash Commands

def categorize_bash(command: str) -> str:
    """Classify a Bash command into a semantic category."""
    if "git grep" in command: return "git-grep"
    if "git show" in command: return "git-show"
    if "git log" in command:  return "git-log"
    if "git diff" in command: return "git-diff"
    if "bootstrap" in command or "python3" in command: return "bootstrap"
    if any(x in command for x in ["cat ", "head ", "tail "]): return "file-read-bash"
    if "ls " in command or "find " in command: return "file-list"
    return "other"

Extract Token Usage

IMPORTANT: input_tokens alone is misleading — it only counts non-cached input. Real input cost = input_tokens + cache_creation_input_tokens + cache_read_input_tokens. The output_tokens field includes both visible text and hidden thinking tokens (see Gotchas).

def extract_token_usage(filepath: str) -> dict:
    """Sum token usage across all assistant turns, including cache tokens."""
    total_input = 0
    total_output = 0
    total_cache_create = 0
    total_cache_read = 0
    with open(filepath) as f:
        for line in f:
            line = line.strip()
            if not line:
                continue
            try:
                entry = json.loads(line)
            except json.JSONDecodeError:
                continue
            msg = entry.get("message", {})
            if isinstance(msg, dict):
                usage = msg.get("usage", {})
                total_input += usage.get("input_tokens", 0)
                total_output += usage.get("output_tokens", 0)
                total_cache_create += usage.get("cache_creation_input_tokens", 0)
                total_cache_read += usage.get("cache_read_input_tokens", 0)
    return {
        "input_tokens": total_input,
        "output_tokens": total_output,
        "cache_creation_input_tokens": total_cache_create,
        "cache_read_input_tokens": total_cache_read,
        "effective_input": total_input + total_cache_create + total_cache_read,
    }

Existing Analysis Scripts

When this skill loads, Claude Code provides a "Base directory for this skill" path. The plugin root is two levels up from that path. Derive it once and use it for all script references:

# PLUGIN_ROOT = base directory minus "skills/analyzing-cc-sessions"
# Example: if base dir is ~/.claude/plugins/cache/.../pirategoat-tools/1.43.3/skills/analyzing-cc-sessions
# then PLUGIN_ROOT is ~/.claude/plugins/cache/.../pirategoat-tools/1.43.3
PLUGIN_ROOT="${CLAUDE_SKILL_DIR}/../.."

When you need to...	Use
Trace tool call sequences for a specific agent type	${CLAUDE_SKILL_DIR}/../../scripts/analysis/session_analyzer.py
Compare metrics (tokens, duration, findings) across sessions	${CLAUDE_SKILL_DIR}/../../scripts/analysis/session_metrics.py
Do something not covered above	Write a targeted script using the parsing recipes in this skill

Quick Start

# Derive plugin root from skill base directory (provided by Claude Code on skill load)
PLUGIN_ROOT="${CLAUDE_SKILL_DIR}/../.."

# Analyze specific agent type across recent sessions
python3 "$PLUGIN_ROOT/scripts/analysis/session_analyzer.py" \
    --sessions-dir ~/.claude/projects/<project-path-hash> \
    --agent patterns-reviewer --max-sessions 20

# Extract metrics from a specific session
python3 "$PLUGIN_ROOT/scripts/analysis/session_metrics.py" \
    --sessions-dir ~/.claude/projects/<project-path-hash> \
    --limit 5

Common Analysis Patterns

Efficiency Analysis

Extract all tool calls first, then classify each one in a single pass. Focus on boundaries between phases (bootstrap → search → analysis → write) — waste clusters at phase transitions where the agent re-orients.

For each subagent dispatch, classify every tool call as productive or wasted:

Category	Productive	Wasted
Bootstrap	First successful run	Retries, cascade reads
git grep	Unique searches with results	Duplicate queries, bare symbol searches
git show	Files needed for analysis	Same-directory files read individually
Read	Unique files for context	Re-reads of own output, tool-results re-reads
Write	Successful output writes	API hallucination attempts, wrong method names
Post-write	—	Verification reads after save() succeeds

Efficiency % = productive calls / total calls

Typical ranges: 50-85% depending on agent and PR size.

Common Waste Patterns (Ranked by Impact)

1. API hallucination — Wrong method names on first write attempt (e.g., add_finding() instead of add_issue()). Agent introspects, retries. ~3 wasted calls/dispatch.
2. Bootstrap size cascade — Output >30KB gets persisted; agent re-reads the persisted file which is even larger; cascades until agent uses offset/limit. ~2-3 wasted calls on large PRs.
3. Post-write verification — Reading output files after save() already confirmed success. ~1-2 calls/dispatch.
4. Duplicate searches — Same git grep pattern run multiple times. Often 2-4 duplicates per dispatch.
5. Sibling tool call cascade — When parallel tool calls include one that fails (e.g., file path error), ALL sibling calls in the batch fail with "Sibling tool call errored".

Cross-Session Comparison

When comparing multiple sessions for the same agent type, track:

• Tool call count distribution (min/max/avg)
• Finding count vs tool calls (efficiency ratio)
• Model used (Opus vs Sonnet vs Haiku — different cost profiles)
• Runtime (first_timestamp to last_timestamp)
• Verdict distribution (APPROVE / COMMENT / REQUEST_CHANGES)

Gotchas

Trap	Reality
content is always a list	No — human messages use plain string, tool results use list
Progress entries are useful	Mostly noise (~60-70% of entries). Only agent_progress has useful agentId
All agent-*.jsonl files are real agents	agent-acompact-* files are system compaction agents — use is_task_agent() to filter
Tool result content is always inline	Large outputs (>~30KB) are persisted to tool-results/{id}.txt
Session JSONL = chronological	Mostly yes, but parallel tool calls create interleaved entries
model is on the entry	No — model is inside message on assistant entries: entry.message.model
usage is on the entry	Sometimes on the entry itself, sometimes inside message.usage — check both
Subagents have thinking blocks	No. Thinking blocks are stripped from subagent JSONL entirely. Main session records them but with redacted content (empty thinking field + signature). To detect thinking in subagents, compare output_tokens to visible output (text chars + tool_use input chars) / 4. A gap of 20-40% is typical and represents hidden thinking tokens.
input_tokens = total input cost	No. input_tokens only counts non-cached tokens (often single digits). Real input = input_tokens + cache_creation_input_tokens + cache_read_input_tokens. Using input_tokens alone will undercount by 99%+.
output_tokens = visible output	No. output_tokens includes both visible text/tool_use AND hidden extended thinking tokens. There is no separate field for thinking tokens in the usage data.