session-inspector

Original：🇺🇸 English
Translated

This skill should be used when inspecting, analyzing, or querying Claude Code session logs. Use when users ask about session history, want to find sessions, analyze context usage, extract tool call patterns, debug agent execution, or understand what happened in previous sessions. Essential for understanding Claude Code's ~/.claude/projects/ structure, JSONL session format, and the erk extraction pipeline.

5installs
Sourcedagster-io/erk
Added on

NPX Install

npx skill4agent add dagster-io/erk session-inspector

Tags

Translated version includes tags in frontmatter
claude-codesession-inspectionagent-debugginglog-analysiscli-tool

SKILL.md Content

View Translation Comparison →

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>
:
CommandPurpose
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

CommandPurpose
/erk:sessions-list
Display formatted session list table
/local:analyze-context
Analyze context window usage across sessions

Core Capabilities

1. List Sessions

bash
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

bash
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

bash
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

bash
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

bash
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

bash
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:
  1. Hook receives session context via stdin JSON from Claude Code
  2. Hook outputs 
    📌 session: <id>
    reminder to conversation
  3. Agent extracts session ID from reminder text
  4. Agent passes session ID as explicit CLI parameter
Example:
bash
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/<session-id>/
:
python
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

  1. List sessions: 
    erk exec list-sessions
  2. Find by summary or time
  3. Preprocess: 
    erk exec preprocess-session <file> --stdout | head -500

Debug Context Blowout

  1. Run 
    /local:analyze-context
  2. Check token breakdown by category
  3. Look for duplicate reads or large tool results

Extract Plan for Implementation

bash
erk exec extract-latest-plan --session-id <id>

Create Issue from Session Plan

bash
erk exec create-pr-from-session --session-id <id>

Find Agent Subprocess Logs

bash
# 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

bash
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/