| name | session-transcript-analyzer |
| description | Parses and merges Claude .jsonl transcripts with debug logs to generate a timeline heuristics report of API limits, context overflows, hook blocks, and tool failures. |
| version | 1 |
| model | sonnet |
| invoked_by | both |
| user_invocable | true |
| tools | ["Read","Write","Bash"] |
| verified | true |
| lastVerifiedAt | "2026-03-08T21:09:19.891Z" |
| best_practices | ["Follow existing project patterns","Document all outputs clearly","Handle errors gracefully"] |
| error_handling | graceful |
| streaming | supported |
| source | builtin |
| trust_score | 100 |
| provenance_sha | 47004af1234a541f |
Session Transcript Analyzer
Session Transcript Analyzer Skill - Parses and merges Claude .jsonl transcripts with debug logs to generate a timeline heuristics report of API limits, context overflows, hook blocks, and tool failures.
- Locate Claude Code session transcripts (`.jsonl`) in `~/.claude/projects/` by session ID or by recency
- Pair each transcript with its corresponding debug log (`.txt`) in `~/.claude/debug/`
- Parse JSONL transcript events: count user turns, tool invocations, and tool errors
- Parse debug log lines: detect router lockdown violations, context-length overflows, and JSON parse failures
- Generate a structured Markdown report with overview metrics, tool usage summary, and heuristic findings
- Write report to `.tmp/transcript-analysis-.md` or a caller-specified path
Step 1: Locate the transcript
Determine the target session. Two modes:
- Explicit session ID: pass
--session <uuid> to scan ~/.claude/projects/<project-dir>/ for a .jsonl file whose name contains the UUID.
- Auto-detect (no
--session): scan the project directory (derived from process.cwd()) for the most recently modified .jsonl file. Fall back to a global scan of ~/.claude/projects/ if the project directory does not exist.
Project folder name derivation: replace the drive colon+backslash with --, then replace remaining path separators with -.
Example: C:\dev\projects\agent-studio → C--dev-projects-agent-studio.
Step 2: Pair with a debug log
Once the session ID is extracted from the transcript filename (<uuid>.jsonl), look for a matching debug log at ~/.claude/debug/<uuid>.txt. If not found, do a prefix/contains scan of the debug directory. Warn but continue if no debug log is found.
Step 3: Parse the JSONL transcript
Read the file line by line. Skip blank or malformed lines. For each valid JSON object:
- Count user messages:
event.type === 'user' where event.message.content[0].type === 'text'
- Count tool invocations: content blocks with
type === 'tool_use'; accumulate per-tool counts in a frequency map
- Collect tool failures: content blocks with
type === 'tool_result' and is_error === true
Step 4: Parse the debug log
**Analyze the most recent session (auto-detect):**
