claude-devtools-inspector

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

claude-devtools Inspector

Skill by ara.so — Devtools Skills collection.

claude-devtools is the missing DevTools for Claude Code. It reads session logs from

~/.claude/

and reconstructs everything Claude Code hides: tool calls, token usage, subagent trees, thinking steps, context window breakdown, and memory layers. Works with all existing sessions — no wrapper, no API keys, no configuration.

由ara.so开发的Skill — Devtools Skills合集。

claude-devtools是Claude Code缺失的DevTools工具。它读取

~/.claude/

目录下的会话日志，还原Claude Code隐藏的所有内容：工具调用、令牌使用情况、子代理树、思考步骤、上下文窗口分解以及内存层。适用于所有现有会话——无需包装器、无需API密钥、无需配置。

What claude-devtools Does

claude-devtools的功能

Session inspection: View full transcripts of any Claude Code session with syntax-highlighted messages
Tool call visibility: See exact inputs/outputs for Read, Edit, Bash, Search, and all other tools
Token attribution: Per-turn breakdown across 7 categories (CLAUDE.md, skills, @-mentions, tool I/O, thinking, team overhead, user text)
Context compaction: Visualize when context hits limits and what gets compressed/dropped
Subagent trees: Isolated execution traces for nested agents with cost/duration metrics
Memory viewer: Browse project memory layers stored in
```
~/.claude/projects/<project>/memory/
```
Thinking steps: Full extended thinking content that's invisible in the terminal
Copy/paste: Export sessions to Markdown/JSON, one-click copy on code blocks

会话检查：查看任意Claude Code会话的完整记录，消息支持语法高亮
工具调用可见性：查看Read、Edit、Bash、Search及所有其他工具的精确输入/输出
令牌归因：按7个类别（CLAUDE.md、skills、@提及、工具I/O、思考内容、团队开销、用户文本）逐轮分解令牌使用情况
上下文压缩可视化：可视化上下文达到限制时的情况，以及哪些内容被压缩/丢弃
子代理树：带成本/时长指标的嵌套代理独立执行轨迹
内存查看器：浏览存储在
```
~/.claude/projects/<project>/memory/
```
中的项目内存层
思考步骤：终端中不可见的完整扩展思考内容
复制粘贴：将会话导出为Markdown/JSON格式，代码块一键复制

Installation

安装

Desktop App (macOS)

桌面应用（macOS）

bash

undefined

bash

undefined

Homebrew

brew install --cask claude-devtools

Or download from releases

或从发布页面下载

open https://github.com/matt1398/claude-devtools/releases/latest

undefined

open https://github.com/matt1398/claude-devtools/releases/latest

undefined

Docker / Standalone Server

Docker / 独立服务器

bash

undefined

bash

undefined

Using docker-compose

使用docker-compose

docker compose up

Or manual docker run

或手动docker运行

docker build -t claude-devtools . docker run -p 3456:3456 -v ~/.claude:/data/.claude:ro claude-devtools

Open http://localhost:3456

打开 http://localhost:3456

undefined

undefined

Build from Source

从源码构建

bash

git clone https://github.com/matt1398/claude-devtools.git
cd claude-devtools
pnpm install
pnpm dev  # Development mode with hot reload
pnpm build  # Production build

bash

git clone https://github.com/matt1398/claude-devtools.git
cd claude-devtools
pnpm install
pnpm dev  # 带热重载的开发模式
pnpm build  # 生产构建

Key Configuration

关键配置

claude-devtools reads from

~/.claude/

by default. No config files needed.

claude-devtools默认从

~/.claude/

读取数据。无需配置文件。

Environment Variables (Docker/Standalone)

环境变量（Docker/独立模式）

bash

undefined

bash

undefined

.env or docker-compose environment

.env或docker-compose环境变量

CLAUDE_ROOT=~/.claude # Path to Claude data directory HOST=0.0.0.0 # Bind address PORT=3456 # Listen port

undefined

CLAUDE_ROOT=~/.claude # Claude数据目录路径 HOST=0.0.0.0 # 绑定地址 PORT=3456 # 监听端口

undefined

Custom Claude Directory

自定义Claude目录

If your Claude data is in a non-standard location:

bash

undefined

如果你的Claude数据位于非标准位置：

bash

undefined

Docker

docker run -p 3456:3456 -v /custom/path:/data/.claude:ro claude-devtools

Desktop app: use "Open Custom Directory" in UI

桌面应用：在UI中使用“打开自定义目录”

undefined

undefined

Session Log Format

会话日志格式

Claude Code writes JSONL logs to

~/.claude/sessions/<session-id>.jsonl

. Each line is a JSON object:

typescript

interface SessionLogEntry {
  type: 'user' | 'assistant' | 'tool_use' | 'tool_result' | 'thinking' | 'team_message';
  timestamp: string;
  content?: string;
  tool_name?: string;
  tool_input?: Record<string, unknown>;
  tool_output?: string;
  tokens?: {
    input: number;
    output: number;
    cache_read?: number;
    cache_creation?: number;
  };
  context?: {
    used: number;
    limit: number;
    segments: { type: string; tokens: number }[];
  };
}

Claude Code将JSONL日志写入

~/.claude/sessions/<session-id>.jsonl

。每一行是一个JSON对象：

typescript

interface SessionLogEntry {
  type: 'user' | 'assistant' | 'tool_use' | 'tool_result' | 'thinking' | 'team_message';
  timestamp: string;
  content?: string;
  tool_name?: string;
  tool_input?: Record<string, unknown>;
  tool_output?: string;
  tokens?: {
    input: number;
    output: number;
    cache_read?: number;
    cache_creation?: number;
  };
  context?: {
    used: number;
    limit: number;
    segments: { type: string; tokens: number }[];
  };
}

Common Use Cases

常见用例

Inspect a Running Session

检查运行中的会话

bash

undefined

bash

undefined

Start Claude Code in terminal

在终端启动Claude Code

claude code --session my-task

In claude-devtools UI:

在claude-devtools UI中：

1. Open app (or navigate to http://localhost:3456 if using Docker)

1. 打开应用（如果使用Docker则导航至http://localhost:3456）

2. Session appears automatically in sidebar

2. 会话会自动出现在侧边栏中

3. Click to view live updates

3. 点击查看实时更新

undefined

undefined

Find High Token Usage

查找高令牌使用情况

typescript

// Use the UI token filter
// Or query JSONL directly with jq
cat ~/.claude/sessions/<session-id>.jsonl \
  | jq 'select(.tokens.input > 10000) | {timestamp, tokens}'

typescript

// 使用UI令牌过滤器
// 或直接用jq查询JSONL
cat ~/.claude/sessions/<session-id>.jsonl \
  | jq 'select(.tokens.input > 10000) | {timestamp, tokens}'

Export Session Transcript

导出会话记录

bash

undefined

bash

undefined

In claude-devtools UI:

在claude-devtools UI中：

1. Open session

1. 打开会话

2. Click "Export" button (top right)

2. 点击右上角的“导出”按钮

3. Choose format: Markdown, JSON, or Plain Text

3. 选择格式：Markdown、JSON或纯文本

Result includes all messages, tool calls, and thinking steps

结果包含所有消息、工具调用和思考步骤

undefined

undefined

Debug Context Compaction

调试上下文压缩

When Claude "forgets" earlier context:

Open session in claude-devtools
Navigate to Context tab
Look for red/orange segments in token visualization
Hover over compacted segments to see what was dropped
Click "Show Compaction Events" to see exact turn numbers

当Claude“遗忘”早期上下文时：

在claude-devtools中打开会话
导航至“上下文”标签页
在令牌可视化中查找红色/橙色片段
悬停在压缩片段上查看被丢弃的内容
点击“显示压缩事件”查看精确的轮次编号

Review Tool Calls

查看工具调用

bash

undefined

bash

undefined

In UI: Filter by tool type

在UI中：按工具类型筛选

Supported filters:

支持的筛选条件：

- Tool: Read, Edit, Bash, Search, ListDir, etc.

- 工具：Read、Edit、Bash、Search、ListDir等

- Status: success, error

- 状态：成功、错误

- Contains: regex pattern match on input/output

- 包含：输入/输出的正则模式匹配

undefined

undefined

Check Subagent Activity

检查子代理活动

typescript

// Subagent trees show:
// - Agent hierarchy (parent → child)
// - Tool calls per agent
// - Token usage per agent
// - Duration and cost breakdown

// In UI: Click "Subagents" tab
// Nested agents render recursively with full tool traces

typescript

// 子代理树显示：
// - 代理层级（父→子）
// - 每个代理的工具调用
// - 每个代理的令牌使用情况
// - 时长和成本分解

// 在UI中：点击“子代理”标签页
// 嵌套代理会递归渲染并显示完整工具轨迹

View Project Memory

查看项目内存

bash

undefined

bash

undefined

Claude stores memory at:

Claude将内存存储在：

~/.claude/projects/<project-id>/memory/

├── MEMORY.md # Index of layers

├── MEMORY.md # 层索引

├── working-style.md # Layer content

├── working-style.md # 层内容

├── architecture.md

└── ...

In claude-devtools:

在claude-devtools中：

1. Click "Memory" in sidebar

1. 点击侧边栏中的“内存”

2. Browse layers as clickable index

2. 浏览可点击的层索引

3. Click "Open in..." to launch in Cursor/VS Code/etc.

3. 点击“在...中打开”在Cursor/VS Code等工具中启动

undefined

undefined

SSH Remote Sessions

SSH远程会话

Inspect sessions on remote machines:

typescript

// claude-devtools reads ~/.ssh/config automatically
// In UI: Settings → Remote → Add SSH Connection

// Example ~/.ssh/config:
Host prod-server
  HostName 192.168.1.100
  User deploy
  IdentityFile ~/.ssh/id_rsa

// In claude-devtools: Select "prod-server"
// Sessions from remote ~/.claude appear in sidebar

检查远程机器上的会话：

typescript

// claude-devtools会自动读取~/.ssh/config
// 在UI中：设置→远程→添加SSH连接

// ~/.ssh/config示例：
Host prod-server
  HostName 192.168.1.100
  User deploy
  IdentityFile ~/.ssh/id_rsa

// 在claude-devtools中：选择“prod-server”
// 远程~/.claude中的会话会出现在侧边栏中

Notification Setup

通知设置

Trigger alerts on specific events:

typescript

// In UI: Settings → Notifications

// Built-in triggers:
{
  ".env access": {
    pattern: "\\.env",
    field: "tool_input.path"
  },
  "High token usage": {
    threshold: 50000,
    field: "tokens.input"
  },
  "Tool error": {
    field: "tool_output",
    contains: "error|failed|exception"
  }
}

// Custom regex trigger:
{
  "API key exposure": {
    pattern: "(sk-[A-Za-z0-9]{32}|ghp_[A-Za-z0-9]{36})",
    field: "content"
  }
}

针对特定事件触发警报：

typescript

// 在UI中：设置→通知

// 内置触发器：
{
  ".env访问": {
    pattern: "\\.env",
    field: "tool_input.path"
  },
  "高令牌使用": {
    threshold: 50000,
    field: "tokens.input"
  },
  "工具错误": {
    field: "tool_output",
    contains: "error|failed|exception"
  }
}

// 自定义正则触发器：
{
  "API密钥暴露": {
    pattern: "(sk-[A-Za-z0-9]{32}|ghp_[A-Za-z0-9]{36})",
    field: "content"
  }
}

Troubleshooting

故障排除

Session Not Appearing

会话未显示

bash

undefined

bash

undefined

Check Claude data directory exists

检查Claude数据目录是否存在

ls -la ~/.claude/sessions/

Verify permissions

验证权限

chmod 755 ~/.claude chmod 644 ~/.claude/sessions/*.jsonl

Force refresh in UI: Cmd+R (macOS) / Ctrl+R (Linux/Windows)

在UI中强制刷新：Cmd+R（macOS）/ Ctrl+R（Linux/Windows）

undefined

undefined

Docker Volume Mount Issues

Docker卷挂载问题

bash

undefined

bash

undefined

Ensure read permissions on host

确保主机有读取权限

chmod -R 755 ~/.claude

Use absolute paths in docker-compose.yml

在docker-compose.yml中使用绝对路径

volumes:

/home/user/.claude:/data/.claude:ro

volumes:

/home/user/.claude:/data/.claude:ro

Check mount inside container

在容器内检查挂载情况

docker exec <container-id> ls -la /data/.claude/sessions

undefined

docker exec <container-id> ls -la /data/.claude/sessions

undefined

Incomplete Session Data

会话数据不完整

bash

undefined

bash

undefined

Claude Code only writes logs for:

Claude Code仅为以下情况写入日志：

- Sessions with --session flag

- 使用--session标志的会话

- Project-level sessions (not global prompts)

- 项目级会话（非全局提示）

Missing thinking steps? Check Claude Code version

缺少思考步骤？检查Claude Code版本

claude --version # Thinking logs added in v2.2.0+

claude --version # 思考日志在v2.2.0+版本中添加

Verify JSONL integrity

验证JSONL完整性

jq empty ~/.claude/sessions/<session-id>.jsonl

undefined

jq empty ~/.claude/sessions/<session-id>.jsonl

undefined

High Memory Usage (Large Sessions)

内存占用过高（大型会话）

bash

undefined

bash

undefined

Sessions with >100k tokens may consume significant RAM

令牌数>100k的会话可能占用大量内存

Solutions:

解决方案：

1. Close unused session tabs in UI

1. 在UI中关闭未使用的会话标签页

2. Use "Export" → "JSON" and analyze offline

2. 使用“导出”→“JSON”并离线分析

3. Increase Docker memory limit:

3. 增加Docker内存限制：

docker run -m 4g -p 3456:3456 claude-devtools

undefined

docker run -m 4g -p 3456:3456 claude-devtools

undefined

macOS Gatekeeper Block

macOS Gatekeeper拦截

bash

undefined

bash

undefined

On first launch, right-click app → Open

首次启动时，右键点击应用→打开

Or disable quarantine:

或解除隔离：

xattr -d com.apple.quarantine /Applications/claude-devtools.app

undefined

xattr -d com.apple.quarantine /Applications/claude-devtools.app

undefined

API Reference (Standalone Mode)

API参考（独立模式）

When running as a server (Docker/Node), claude-devtools exposes:

typescript

// List all sessions
GET /api/sessions
// Response: { sessions: [{ id, timestamp, title }] }

// Get session detail
GET /api/sessions/:id
// Response: { session: { id, messages: [...] } }

// Export session
GET /api/sessions/:id/export?format=markdown|json|txt
// Response: Content-Type varies by format

// Health check
GET /health
// Response: { status: "ok", version: "1.x.x" }

当以服务器模式运行（Docker/Node）时，claude-devtools提供以下API：

typescript

// 列出所有会话
GET /api/sessions
// 响应：{ sessions: [{ id, timestamp, title }] }

// 获取会话详情
GET /api/sessions/:id
// 响应：{ session: { id, messages: [...] } }

// 导出会话
GET /api/sessions/:id/export?format=markdown|json|txt
// 响应：Content-Type随格式变化

// 健康检查
GET /health
// 响应：{ status: "ok", version: "1.x.x" }

Integration with Claude Code

与Claude Code集成

bash

undefined

bash

undefined

Run Claude Code with session logging

启用会话日志运行Claude Code

claude code --session my-feature

Session appears instantly in claude-devtools

会话会立即出现在claude-devtools中

Live updates as Claude executes tools

当Claude执行工具时实时更新

Use claude-devtools to:

使用claude-devtools可以：

- Monitor token usage during long sessions

- 监控长会话中的令牌使用情况

- Verify which files Claude read/edited

- 验证Claude读取/编辑了哪些文件

- Debug subagent spawning issues

- 调试子代理生成问题

- Export transcript for team review

- 导出记录供团队评审

undefined

undefined

Performance Tips

性能提示

bash

undefined

bash

undefined

Limit session retention

限制会话保留时间

Delete old sessions to reduce scan time:

删除旧会话以减少扫描时间：

find ~/.claude/sessions -mtime +30 -delete

Index large sessions

为大型会话建立索引

claude-devtools caches parsed sessions in memory

claude-devtools会在内存中缓存解析后的会话

First load may be slow for 100+ MB logs

首次加载100+ MB日志可能较慢

Use filters early

尽早使用筛选器

Apply tool/timestamp filters before expanding messages

在展开消息前应用工具/时间戳筛选器

undefined

undefined

Security Notes

安全说明

claude-devtools is read-only — never modifies session logs
Standalone server has zero outbound network calls

For maximum isolation:

docker run --network none -p 3456:3456 -v ~/.claude:/data/.claude:ro claude-devtools

See
```
SECURITY.md
```
in repo for full threat model

claude-devtools是只读工具——绝不会修改会话日志
独立服务器无任何出站网络调用

如需最大隔离性：

docker run --network none -p 3456:3456 -v ~/.claude:/data/.claude:ro claude-devtools

如需完整威胁模型，请查看仓库中的
```
SECURITY.md
```

Development Commands

开发命令

bash

undefined

bash

undefined

Run tests

运行测试

pnpm test

Type checking

类型检查

pnpm typecheck

Lint

代码检查

pnpm lint

Full quality gate (types + lint + test + build)

完整质量检查（类型+代码检查+测试+构建）

pnpm check

Build Electron app

构建Electron应用

pnpm build

undefined

pnpm build

undefined

Resources

资源

Documentation: https://claude-dev.tools/docs
JSONL format reference: https://claude-dev.tools/docs/jsonl-format
Comparison with
```
--verbose
```
: https://claude-dev.tools/docs/verbose-vs-devtools
Debugging walkthrough: https://claude-dev.tools/docs/why-claude-forgot
GitHub issues: https://github.com/matt1398/claude-devtools/issues

文档：https://claude-dev.tools/docs
JSONL格式参考：https://claude-dev.tools/docs/jsonl-format
与
```
--verbose
```
的对比：https://claude-dev.tools/docs/verbose-vs-devtools
调试指南：https://claude-dev.tools/docs/why-claude-forgot
GitHub问题：https://github.com/matt1398/claude-devtools/issues