mindwalk
一款可视化工具，能在代码库的 3D 地图上回放编码智能体的会话过程。
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 页面获取。从源码构建：执行 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] <session.jsonl> open one specific session
mindwalk build <repo> [-o out] write the repository citymap JSON
mindwalk trace <session> [-o out] write the normalized trace JSON
解读画面
- 树状 / 地形视图——将代码仓库呈现为径向树状图或简单的矩形树状图；发光程度 ∝ 文件被触及的深度和频率。
- 触及状态——每个文件保留其最深层的触及状态：已查看（苔藓绿）、已读取（月光白）、已编辑（暖琥珀色）、未访问（暗色）。HUD 将摩擦信号——错误率、反复修改的文件、最后一次验证后的编辑——整合到一条审查条中。
- 回放控制台——可在会话运行的分桶直方图上拖拽或播放。条形图位于冷/暖色光谱上：观察行为保持冷色调（搜索、读取、执行），修改行为呈现暖色调（编辑、验证），因此编辑阶段一目了然。
- 时间线标记——◇ 上下文压缩、○ 子智能体启动、› 用户交互；每个标记都是可点击跳转的目标。
- 检查器——点击文件可固定其访问历史；点击某次访问行可将播放头跳转到该时刻。
键盘快捷键：Space 播放/暂停 · ←/→ 单步（⇧ 为 10 倍步进）· Home/End 跳转至首尾 · S 调整速度 · E 跳至下一处编辑 · X 跳至下一个错误 · M 跳至下一个标记 · ⌘B 打开会话侧栏。
底层架构
两个工件，刻意保持分离：
- 一条轨迹——将会话日志归一化为按序排列的文件触碰事件流（位于 internal/adapter，每种智能体格式对应一个适配器）；
- 一张城市地图——仓库的确定性布局（位于 internal/citymap）；相同的代码树始终生成相同的地图，因此不同会话间的回放具有可比性。
一个本地 Go 服务器（位于 internal/server）将两者结合，并为 React/Three.js 前端（web 目录）提供服务。schema/ 目录镜像了导出的 JSON 合约。
贡献指南
欢迎提交 Issue 和拉取请求。要搭建可用的开发环境，请按以下步骤操作：
make setup # install frontend dependencies
make serve # dev server on :8765, serving web/dist from the working tree
make test # go test + frontend build — run before sending a PR
make build # regenerate embedded assets and bin/mindwalk
基本原则（完整架构说明请参见 AGENTS.md）：
- 保持边界清晰：适配器不关心渲染逻辑，城市地图生成不依赖回放功能，服务器仅负责连接两者。
- 保持 Go 代码符合 gofmt 格式规范；切勿手动编辑 internal/server/static 目录——请使用 make build 命令重新生成。
- 当轨迹或城市地图的 JSON 结构发生变化时，需在同一变更中同步更新 schema/ 目录及相关的测试文件。