session-inspector_skill

Overview

This skill inspects, analyzes, and queries Claude Code session logs stored under ~/.claude/projects/. It helps you discover sessions, preprocess logs into readable XML, extract plans, analyze context-window usage, and debug agent subprocesses. Use it to turn raw JSONL session data into actionable insights and reproducible artifacts like GitHub issues.

How this skill works

The skill drives the erk CLI to list session metadata, preprocess JSONL logs into compressed XML, and run a two-stage extraction pipeline (mechanical reduction then optional semantic distillation). It reads encoded project directories, locates session and agent subprocess logs, computes context-token breakdowns, and extracts the most recent plan or the full rendered session for issue creation. Outputs include XML, summarized JSON, and GitHub issue metadata.

When to use it

• You need to find what happened in a past Claude Code session or locate a session by ID
• You want to analyze context-window consumption or identify token-heavy inputs
• You need to extract the most recent plan from a session for implementation or reporting
• You must debug agent subprocess failures or inspect agent-* logs
• You want to publish or reconstruct session content as a GitHub issue or comment

Best practices

• Start with erk exec list-sessions to narrow candidates before preprocessing large logs
• Preprocess to compressed XML (--stdout for piping) to reduce noise before deep analysis
• Use --session-id explicitly to avoid ambiguous session selection rules
• Run the two-stage extraction: deterministic mechanical reduction first, then semantic distillation if you need human-readable summaries
• Keep session-scoped scratch files under .erk/scratch/sessions/<session-id> for reproducibility

Example use cases

• Locate a session by recent edit time and extract its plan for a PR or issue
• Analyze context token breakdowns to diagnose context blowouts and trim redundant reads
• Preprocess a large JSONL to XML and render it as chunked GitHub comments for long-session sharing
• List agent subprocess logs to find and inspect errors or stack traces from helper agents
• Create a GitHub issue automatically from an extracted session plan to track follow-up work