claude-devtools：给 Claude Code 装上透视眼

你有没有过这种感觉：Claude Code 在终端里嗒嗒嗒跑了一堆命令，输出一行行模糊的摘要——「Read 3 files」「Edited 2 files」——可你根本不知道它到底读了什么、改了什么、想什么。

这种感觉，就像蒙着眼睛让一个工程师帮你装修房子：你知道他在干活，但完全看不见他在干什么。

claude-devtools 就是来解决这个问题的。它是一个开源的本地调试工具，专门为 Claude Code 设计，可以把 Claude Code 那些藏在终端里的日志，重新还原成一个可视化界面——文件路径、行号、diff 变更、Token 消耗、子 Agent 执行树，全部一目了然。

背景：Claude Code 的「降级」引发的社区愤怒

2025 年，Anthropic 发布了 Claude Code v2.1.20，这个版本用简短的摘要替换了原本详细的执行输出。社区在 Hacker News 上表达了强烈不满：AI 工具的核心价值在于「可观测性」（Observability）——如果连开发者都不知道 AI 做了什么，还怎么信任它、调试它？

作者 matt1398 就是在这波讨论中受到启发，开发了 claude-devtools。工具发布后在社交媒体和开发者社区迅速传播，GitHub Stars 在数周内突破 3000，成为 Claude Code 生态中下载量最高的第三方工具之一。

核心功能：还原 Claude Code 的盲区

claude-devtools 的本质是一个日志解析器+可视化渲染器。它读取本机 ~/.claude/ 目录下的会话记录文件，然后重建出一个完整的交互式界面。

1. 上下文窗口可视化

Claude Code 的上下文窗口是个「黑盒」，你只知道用了多少 Token，不知道这些 Token 被什么占用了。claude-devtools 将上下文消耗拆分成 7 个维度：CLAUDE.md 全局配置、项目级配置、目录级配置、Skills、@提及的文件、工具调用的输入输出、思考过程、团队协作开销、用户原始文本。配合上下文压缩可视化功能，当窗口即将触达容量上限时，你会看到清晰的「填充-压缩-再填充」图示，精准定位 Claude 为什么会忘记之前的内容。

2. 工具调用检查器

每个工具调用（Read、Edit、Bash 等）都配有专门的查看器：文件读取显示语法高亮和行号；搜索操作展示正则表达式和每条匹配结果；编辑操作用 inline diff 呈现新增/删除内容；Bash 命令输出完整捕获，并标注执行时长。

3. 子 Agent 执行树

Claude Code 的 Team 模式允许一个 Agent 派生出多个子 Agent。普通终端只会显示最终结果，而 claude-devtools 可以递归展开完整的执行树：每个子 Agent 的工具调用序列、Token 消耗、执行时长和费用，全部以树状结构呈现。

4. 项目记忆浏览器

Claude Code 会为每个项目存储记忆文件，位于 ~/.claude/projects/<项目>/memory/。claude-devtools 将其渲染为独立面板：左侧是层级列表，右侧是完整的 Markdown 渲染，支持 Obsidian 风格的 [[双向链接]] 跳转，还可以通过「Open in...」按钮直接在 VS Code、Cursor、Zed 等编辑器中打开任意记忆层。

5. 通知触发器

用户可以配置规则，当 .env 文件被访问、工具执行出错、Token 消耗超标，或任意正则匹配成功时，系统会弹出桌面通知。再也不必盯着终端等 Claude 操作完。

图1：上下文窗口 Token 消耗拆解 — 7个维度显示每个 Token 花在哪里

如何部署：零门槛上手

claude-devtools 有两条部署路径：

路径一：桌面应用（推荐给普通用户）

通过 Homebrew（macOS）或直接下载对应平台的安装包（macOS 的 .dmg、Windows 的 .exe、Linux 的 AppImage/deb/rpm/pacman）。macOS 首次安装需要右键「打开」以绕过系统安全限制，之后就和普通应用一样使用。安装后打开即自动连接本机的 Claude Code 会话记录。

路径二：Docker 一键部署（推荐给服务器/远程场景）

docker compose up
# 然后浏览器打开 http://localhost:3456

Docker 部署特别适合两种场景：一是在远程服务器上查看 SSH 连接的 Claude Code 会话；二是对网络隔离有严格要求的环境——standalone 模式没有任何出站网络请求，完全离线运行。

源码编译（需要 Node.js 20+ 和 pnpm 10+）：

git clone https://github.com/matt1398/claude-devtools.git
cd claude-devtools
pnpm install
pnpm dev

技术架构

claude-devtools 采用 Electron 桌面应用 + 浏览器内嵌 UI 的架构，主技术栈为 TypeScript + React + Vite。源码使用 electron-vite 作为构建工具链，配合 electron-builder 实现跨平台打包（macOS/Windows/Linux）。

后端日志解析引擎使用 Fastify（轻量 Node.js Web 框架）作为 standalone HTTP 服务器，处理 JSONL 格式的会话文件并提供 REST API。渲染层使用 React + TailwindCSS，通过 postmessage IPC 与 Electron 主进程通信。

代码质量方面，项目配置了完整的 TypeScript 严格类型检查（tsc --noEmit）、ESLint 规范检查、Prettier 格式化，以及 Vitest 单元测试框架（含覆盖率报告），并使用 Knip 进行死代码检测。综合质量评分可达 90/100。

项目文档质量极高：README 覆盖完整的功能演示截图和视频，另有独立文档站 claude-dev.tools/docs 提供逐功能的使用指南和架构说明文档。

局限与注意事项

纯本地工具，无法远程透视 Claude Code 云端 API 调用

claude-devtools 只读取本机 ~/.claude/ 的日志文件，这意味着它只能分析 Claude Code 的本地执行记录。如果你通过 API 方式调用 Claude，则不在它的覆盖范围内。

依赖日志文件格式

工具对 Claude Code 的日志格式有强依赖，如果 Anthropic 未来更改日志格式，可能需要等待工具适配。从当前维护频率来看（最后更新于 2026-05-13），作者仍在活跃更新，风险较低。

不支持上下文压缩过程回放

虽然工具能展示「何时发生压缩」，但无法完全还原压缩前被丢弃的具体内容——这部分信息本身已经不存在于日志中。

行业意义：AI 工具的可观测性觉醒

claude-devtools 的出现，折射出一个更大的趋势：AI 编程工具正在从「执行引擎」向「可协作的开发伙伴」演进，而演进过程中，开发者对 AI 决策过程的可见性需求急剧增长。

从 2024 年 Claude Code 发布、到 2025 年社区对「降级」的不满、再到 claude-devtools 的爆发式传播，这条链路说明：给 AI 加「透视眼」正在成为刚性需求。可以预见，类似的可观测性工具会越来越多，并最终成为 AI 编程 IDE 的内置功能。