Session Inspector

Overview

Session Inspector provides comprehensive tools for inspecting Claude Code session logs stored

in

~/.claude/projects/

. The skill enables:

Discovering and listing sessions for any project/worktree

Preprocessing sessions to readable XML format

Analyzing context window consumption

Extracting plans from sessions

Creating plan PRs from session content

Debugging agent subprocess execution

Understanding the two-stage extraction pipeline

When to Use

Invoke this skill when users:

Ask what sessions exist for a project or worktree

Want to find a specific session by ID or content

Need to analyze context window consumption

Ask about tool call patterns or frequencies

Need to debug agent subprocess failures

Want to extract plans from sessions

Ask about session history or previous conversations

Need to understand session preprocessing or extraction

Quick Reference: CLI Commands

All commands invoked via

erk exec

:

Command

Purpose

list-sessions

List sessions with metadata for current worktree

preprocess-session

Convert JSONL to compressed XML

extract-latest-plan

Extract most recent plan from session

create-pr-from-session

Create plan PR from session plan

extract-session-from-issue

Extract session content from GitHub issue

Slash Commands

Command

Purpose

/erk:sessions-list

Display formatted session list table

/local:analyze-context

Analyze context window usage across sessions

Core Capabilities

1. List Sessions

erk

exec

list-sessions

[

--limit N

]

[

--min-size BYTES

]

Options:

--limit

Maximum sessions to return (default: 10)

--min-size

Minimum file size in bytes to filter tiny sessions (default: 0)

Output includes:

Branch context (current_branch, trunk_branch, is_on_trunk)

Current session ID from SESSION_CONTEXT env var

Sessions array with: session_id, mtime_display, mtime_relative, size_bytes, summary, is_current

Project directory path and filtered count

2. Preprocess Session to XML

erk

exec

preprocess-session

<

log-path

>

[

OPTIONS

]

Options:

--session-id

Filter entries to specific session ID

--include-agents/--no-include-agents

Include agent logs (default: True)

--no-filtering

Disable filtering optimizations

--stdout

Output to stdout instead of temp file Optimizations applied: Empty/warmup session filtering Documentation deduplication (hash markers) Tool parameter truncation (>200 chars) Tool result pruning (first 30 lines, preserves errors) Log discovery operation filtering 3. Extract Plan from Session erk exec extract-latest-plan [ --session-id SESSION_ID ] Extracts most recent plan from session. Uses session-scoped lookup via slug field, falls back to mtime-based lookup if no session-specific plan found. 4. Create Plan PR from Session erk exec create-pr-from-session [ --session-id SESSION_ID ] Extracts plan and creates plan PR with session content. Returns JSON with issue_number and issue_url. 5. Render Session for GitHub erk exec render-session-content --session-file < path

[ --session-label LABEL ] [ --extraction-hints HINTS ] Renders session XML as GitHub comment blocks with automatic chunking for large content. 6. Extract Session from GitHub Issue erk exec extract-session-from-issue < issue-number

[ --output PATH ] [ --session-id ID ] Extracts and combines chunked session content from GitHub issue comments. Directory Structure ~/.claude/projects/ ├── -Users-foo-code-myapp/ ← Encoded project path │ ├── abc123-def456.jsonl ← Main session log │ ├── xyz789-ghi012.jsonl ← Another session │ ├── agent-17cfd3f4.jsonl ← Agent subprocess log │ └── agent-2a3b4c5d.jsonl ← Another agent log Path encoding: Prepend - , replace / and . with - Example: /Users/foo/code/myapp → -Users-foo-code-myapp Session ID Session IDs are passed explicitly to CLI commands via --session-id options. The typical flow: Hook receives session context via stdin JSON from Claude Code Hook outputs 📌 session: reminder to conversation Agent extracts session ID from reminder text Agent passes session ID as explicit CLI parameter Example: erk exec list-sessions --session-id abc123-def456 Two-Stage Extraction Pipeline The extraction system uses a two-stage pipeline: Stage 1: Mechanical Reduction (Deterministic) Drop file-history-snapshot entries Strip usage metadata Remove empty text blocks Compact whitespace (3+ newlines → 1) Deduplicate assistant messages with tool_use Output: Compressed XML Stage 2: Haiku Distillation (Optional, Semantic) Remove noise (log discovery, warmup content) Deduplicate semantically similar blocks Prune verbose outputs Preserves errors, stack traces, warnings Output: Semantically refined XML Session Selection Logic The auto_select_sessions() function uses intelligent rules: On trunk: Use current session only Current session trivial (<1KB) + substantial sessions exist: Auto-select substantial Current session substantial (>=1KB): Use it alone No substantial sessions: Return current even if trivial Scratch Storage Session-scoped files stored in .erk/scratch/sessions// : from erk_shared . scratch import get_scratch_dir , write_scratch_file scratch_dir = get_scratch_dir ( session_id ) file_path = write_scratch_file ( content , session_id = session_id , suffix = ".xml" ) Common Tasks Find What Happened in a Session List sessions: erk exec list-sessions Find by summary or time Preprocess: erk exec preprocess-session --stdout | head -500 Debug Context Blowout Run /local:analyze-context Check token breakdown by category Look for duplicate reads or large tool results Extract Plan for Implementation erk exec extract-latest-plan --session-id < id

Create Issue from Session Plan erk exec create-pr-from-session --session-id < id

Find Agent Subprocess Logs

Compute project dir using Claude Code's path encoding (replace / and . with -)

PROJECT_DIR

" $HOME /.claude/projects/ $( pwd | sed 's|/|-|g; s|.|-|g' ) " ls -lt " $PROJECT_DIR " /agent-*.jsonl | head -10 Check for Errors in Agent cat agent- < id

.jsonl | jq 'select(.message.is_error == true)' Resources references/ tools.md - Complete CLI commands and jq analysis recipes format.md - JSONL format specification and entry types extraction.md - erk_shared extraction module API reference Load references when users need detailed command syntax, format documentation, or programmatic access to extraction capabilities. Code Dependencies This skill documents capabilities that primarily live in: CLI commands: packages/erk-cli/src/erk_cli/commands/ Shared library: packages/erk-shared/src/erk_shared/extraction/ GitHub metadata: packages/erk-shared/src/erk_shared/github/metadata.py Scratch storage: packages/erk-shared/src/erk_shared/scratch/