# Dagster Io Erk Session Inspector > Session Inspector - Skill: `tomevault-io/dagster-io-erk-session-inspector` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/dagster-io-erk-session-inspector` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/dagster-io-erk-session-inspector/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/dagster-io-erk-session-inspector --- # 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 ```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 [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 [--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 [--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: ` 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//`: ```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 --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 ``` ### Create Issue from Session Plan ```bash erk exec create-pr-from-session --session-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-.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/` --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/dagster-io) — claim your Tome and manage your conversions.