cosmtrek/mindwalk

来源: https://github.com/cosmtrek/mindwalk

mindwalk

一个可视化工具，能在代码库的3D地图上回放编码代理会话。

https://github.com/user-attachments/assets/6490cd77-0374-4f36-a6e7-24267d5c61f3

30秒演示 —— 请开启声音。

问题

会话日志记录了代理做了什么，但无法体现它如何理解任务：它认为代码库的哪些部分相关，它在行动前探索了哪里，它的足迹是否符合你心中预期的范围。逐行阅读原始的JSONL文件无法回答这些问题。

思路

将代码库绘制成一张夜间地图，然后像移动的光一样回放会话：代理搜索、读取和编辑的地方，地图会发光——其他区域保持黑暗。代理对任务的理解变成了一目了然的形状。一个Go二进制文件即可读取Claude Code和Codex会话日志，完全本地化运行；会话数据不会离开你的机器。

快速开始

curl -fsSL https://raw.githubusercontent.com/cosmtrek/mindwalk/master/scripts/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"
mindwalk

安装程序会根据 checksums.txt 验证二进制文件，并安装到 ~/.local/bin（可通过 INSTALL_DIR 覆盖；通过 VERSION 锁定特定版本）。Windows 归档文件可在 GitHub Releases 页面 (https://github.com/cosmtrek/mindwalk/releases) 获取。

从源代码构建：make setup && make build → bin/mindwalk。

不带参数运行时，mindwalk 会扫描 ~/.claude/projects 和 ~/.codex/sessions，在随机本地端口启动 UI 并打开浏览器：

mindwalk serve [--port N] [--no-open] [--claude-dir DIR] [--codex-dir DIR]
mindwalk open [--no-open] 打开某个特定会话
mindwalk build [-o out]   写入代码库城市地图 JSON
mindwalk trace [-o out]   写入标准化追踪 JSON

解读画面

• 树视图 / 地形视图 —— 将代码库表示为径向树或简单的矩形树图；发光程度 ∝ 文件被触及的深度与频率。
• 触达状态 —— 每个文件保留其最深触达状态：已查看（苔绿色）、已读取（月光白）、已编辑（暖琥珀色）、未访问（暗色）。HUD 将摩擦信号（错误率、被反复修改的文件、末次验证后的编辑）整合为审查条。
• 回放控制台 —— 在运行的聚合直方图上拖动或播放会话。直方图柱使用冷/暖色光谱：观察行为保持冷色（搜索、读取、执行），修改行为呈现暖色（编辑、验证），因此编辑阶段一目了然。
• 时间轴标记 —— ◇ 上下文压缩，○ 子代理启动，› 用户交互轮次；每个标记均可点击跳转。
• 检查器 —— 点击文件可固定其访问历史；点击某次访问行可将播放头跳至该时刻。

同一会话在地形视图上的效果

键盘快捷键：Space 播放/暂停 · ←/→ 步进（⇧ 步进×10）· Home/End 跳至首尾 · S 速度 · E 下一个编辑 · X 下一个错误 · M 下一个标记 · ⌘B 会话轨道。

内部原理

两个独立且刻意分离的构件：

1. 追踪（trace） —— 将会话日志标准化为有序的文件触达事件流（internal/adapter，每种代理格式对应一个适配器）；
2. 城市地图（citymap） —— 代码库的确定性布局（internal/citymap）；相同的代码树总是生成相同的地图，因此不同会话的回放具有可比性。

一个本地 Go 服务器（internal/server）将两者结合，并服务 React/Three.js 前端（web）。schema/ 目录镜像导出的 JSON 契约。

贡献

欢迎提交 Issue 和 Pull Request。要搭建可用的开发环境：

make setup         # 安装前端依赖
make serve         # 在 :8765 启动开发服务器，从工作目录提供 web/dist
make test          # 运行 go test + 前端构建 —— 提交 PR 前必须执行
make build         # 重新生成内嵌资源及 bin/mindwalk

基本规则（完整架构笔记见 AGENTS.md）：

• 保持边界清晰：适配器不关心渲染，城市地图生成不依赖回放，服务器仅负责连接两者。
• Go 代码需经过 gofmt 格式化；切勿手动编辑 internal/server/static —— 通过 make build 重新生成。
• 当追踪或城市地图 JSON 结构发生变化时，在同一变更中更新 schema/ 及相应的测试。