session-inspector

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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

会话检查器提供了全面的工具，用于检查存储在

~/.claude/projects/

路径下的Claude Code会话日志。本技能支持以下能力：

发现并列出任意项目/工作树的会话
将会话预处理为可读性强的XML格式
分析上下文窗口消耗情况
从会话中提取计划
基于会话内容创建计划PR
调试Agent子进程执行过程
理解两阶段提取流水线

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

当用户有以下需求时可调用本技能：

询问某个项目或工作树存在哪些会话
想要通过ID或内容查找特定会话
需要分析上下文窗口消耗情况
询问工具调用模式或频率
需要调试Agent子进程失败问题
想要从会话中提取计划
询问会话历史或往期对话内容
需要了解会话预处理或提取逻辑

Quick Reference: CLI Commands

快速参考：CLI命令

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

所有命令都通过

erk exec <command>

调用：

Command	Purpose
`list-sessions`	列出当前工作树的会话及元数据
`preprocess-session`	将JSONL转换为压缩XML
`extract-latest-plan`	从会话中提取最新的计划
`create-pr-from-session`	基于会话计划创建计划PR
`extract-session-from-issue`	从GitHub issue中提取会话内容

Slash Commands

斜杠命令

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

Command	Purpose
`/erk:sessions-list`	展示格式化的会话列表表格
`/local:analyze-context`	分析跨会话的上下文窗口使用情况

Core Capabilities

核心能力

1. List Sessions

1. 列出会话

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

bash

erk exec list-sessions [--limit N] [--min-size BYTES]

参数选项：

```
--limit
```
: 返回的最大会话数量（默认值：10）
```
--min-size
```
: 过滤小型会话的最小文件大小（单位：字节，默认值：0）

输出包含：

分支上下文（current_branch当前分支、trunk_branch主干分支、is_on_trunk是否在主干分支）
来自SESSION_CONTEXT环境变量的当前会话ID
会话数组，包含：session_id会话ID、mtime_display修改时间展示、mtime_relative相对修改时间、size_bytes文件大小（字节）、summary摘要、is_current是否为当前会话
项目目录路径和过滤后的会话数量

2. Preprocess Session to XML

2. 将会话预处理为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

bash

erk exec preprocess-session <log-path> [OPTIONS]

参数选项：

```
--session-id
```
: 过滤出指定会话ID的条目
```
--include-agents/--no-include-agents
```
: 是否包含Agent日志（默认值：True）
```
--no-filtering
```
: 关闭过滤优化
```
--stdout
```
: 输出到标准输出而非临时文件

应用的优化逻辑：

过滤空会话/预热会话
文档去重（哈希标记）
工具参数截断（超过200字符部分截断）
工具结果裁剪（保留前30行，错误信息完整保留）
过滤日志发现操作

3. Extract Plan from Session

3. 从会话中提取计划

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.

bash

erk exec extract-latest-plan [--session-id SESSION_ID]

从会话中提取最新的计划。通过slug字段进行会话范围的查找，如果未找到会话专属计划，则回退到基于修改时间的查找逻辑。

4. Create Plan PR from Session

4. 基于会话创建计划PR

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.

bash

erk exec create-pr-from-session [--session-id SESSION_ID]

提取计划并基于会话内容创建计划PR。返回包含issue_number（issue编号）和issue_url（issue链接）的JSON数据。

5. Render Session for GitHub

5. 为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.

bash

erk exec render-session-content --session-file <path> [--session-label LABEL] [--extraction-hints HINTS]

将会话XML渲染为GitHub评论块，针对大内容支持自动分块。

6. Extract Session from GitHub Issue

6. 从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.

bash

erk exec extract-session-from-issue <issue-number> [--output PATH] [--session-id ID]

从GitHub issue评论中提取并合并分块的会话内容。

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

~/.claude/projects/
├── -Users-foo-code-myapp/           ← 编码后的项目路径
│   ├── abc123-def456.jsonl          ← 主会话日志
│   ├── xyz789-ghi012.jsonl          ← 其他会话
│   ├── agent-17cfd3f4.jsonl         ← Agent子进程日志
│   └── agent-2a3b4c5d.jsonl         ← 其他Agent日志

路径编码规则： 前缀添加

，将

和

替换为

示例：

/Users/foo/code/myapp

→

-Users-foo-code-myapp

Session ID

会话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

会话ID通过

--session-id

参数显式传递给CLI命令。典型流程如下：

钩子从Claude Code的标准输入JSON中接收会话上下文
钩子向对话输出
```
📌 session: <id>
```
提示
Agent从提示文本中提取会话ID
Agent将会话ID作为显式CLI参数传递

示例：

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)

阶段1：机械压缩（确定性逻辑）

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

丢弃file-history-snapshot条目
剥离使用元数据
移除空文本块
压缩空白字符（3个及以上换行→1个换行）
对带有tool_use的助手消息去重
输出：压缩后的XML

Stage 2: Haiku Distillation (Optional, Semantic)

阶段2：语义提炼（可选，语义逻辑）

Remove noise (log discovery, warmup content)
Deduplicate semantically similar blocks
Prune verbose outputs
Preserves errors, stack traces, warnings
Output: Semantically refined XML

移除噪声（日志发现、预热内容）
对语义相似的内容块去重
裁剪冗长输出
保留错误、栈追踪、警告信息
输出：语义优化后的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

auto_select_sessions()

函数采用智能规则选择会话：

在主干分支上： 仅使用当前会话
当前会话内容极少（<1KB）且存在内容充足的会话： 自动选择内容充足的会话
当前会话内容充足（>=1KB）： 仅使用当前会话
没有内容充足的会话： 即使当前会话内容极少也返回当前会话

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")

会话级文件存储在

.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

列出会话：
```
erk exec list-sessions
```
通过摘要或时间查找目标会话

预处理会话：

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

执行
```
/local:analyze-context
```
查看按类别划分的Token消耗明细
查找重复读取或过大的工具返回结果

Extract Plan for Implementation

提取计划用于落地实现

bash

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

bash

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

Create Issue from Session Plan

基于会话计划创建Issue

bash

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

bash

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

Find Agent Subprocess Logs

查找Agent子进程日志

bash

undefined

bash

undefined

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

使用Claude Code的路径编码规则计算项目目录（将/和.替换为-）

PROJECT_DIR="$HOME/.claude/projects/$(pwd | sed 's|/|-|g; s|.|-|g')" ls -lt "$PROJECT_DIR"/agent-*.jsonl | head -10

undefined

PROJECT_DIR="$HOME/.claude/projects/$(pwd | sed 's|/|-|g; s|.|-|g')" ls -lt "$PROJECT_DIR"/agent-*.jsonl | head -10

undefined

Check for Errors in Agent

检查Agent中的错误

bash

cat agent-<id>.jsonl | jq 'select(.message.is_error == true)'

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.

```
tools.md
```
- 完整的CLI命令和jq分析脚本
```
format.md
```
- JSONL格式规范和条目类型说明
```
extraction.md
```
- erk_shared提取模块API参考

当用户需要详细的命令语法、格式文档或者提取能力的编程访问方式时，可以加载上述参考文档。

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/

本技能描述的能力主要位于以下模块中：

CLI命令：
```
packages/erk-cli/src/erk_cli/commands/
```

共享库：

packages/erk-shared/src/erk_shared/extraction/

GitHub元数据：

packages/erk-shared/src/erk_shared/github/metadata.py

临时存储：

packages/erk-shared/src/erk_shared/scratch/