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.

2installs

Sourcedagster-io/erk

Added on2026-03-04

NPX Install

npx skill4agent add dagster-io/erk session-inspector

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>

:

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

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:

Hook receives session context via stdin JSON from Claude Code
Hook outputs
```
📌 session: <id>
```
reminder to conversation
Agent extracts session ID from reminder text
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

List sessions:
```
erk exec list-sessions
```
Find by summary or time

Preprocess:

erk exec preprocess-session <file> --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

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/

session-inspector

NPX Install

Tags

SKILL.md Content

Session Inspector

Overview

When to Use

Quick Reference: CLI Commands

Slash Commands

Core Capabilities

1. List Sessions

2. Preprocess Session to XML

3. Extract Plan from Session

4. Create Plan PR from Session

5. Render Session for GitHub

6. Extract Session from GitHub Issue

Directory Structure

Session ID

Two-Stage Extraction Pipeline

Stage 1: Mechanical Reduction (Deterministic)

Stage 2: Haiku Distillation (Optional, Semantic)

Session Selection Logic

Scratch Storage

Common Tasks

Find What Happened in a Session

Debug Context Blowout

Extract Plan for Implementation

Create Issue from Session Plan

Find Agent Subprocess Logs

Check for Errors in Agent

Resources

references/

Code Dependencies