Mindwalk - 代码库会话回放可视化
将编码代理的会话回放为代码库的3D地图，直观展示代理对任务的理解与探索过程。
- Star 数
- ★ 1.4k
- 最近更新
- 2 个月前
- License
- MIT
- 主语言
- Go
- FA 评分
- 59/100 · 缺口较多
30 秒速览
- 运行形态
- 可在哪里用
- 通用 · 跨平台ChatGPT · Codex · Claude Code
- 费用
- 软件免费，模型调用费用自付
- 上手难度
- 低 · 几分钟可跑通
- 开始前需要
- 典型场景
- 开发者希望快速了解一个大型代码库中，编码代理是如何理解任务、在哪些文件上花费时间，从而评估其工作范围是否符合预期。
- 不适合
- 只使用 Cursor、Gemini CLI 等未支持格式的团队
- 不愿让会话摘要发送给模型 API 的隐私敏感团队
- 源码审查
- 59/100 · 缺口较多
这个 Agent 能做什么，适合哪些场景？
Mindwalk 是一个可视化工具，以代码库的 3D「夜景地图」形式回放编码代理的会话日志，让用户直观看到代理在执行任务时搜索、阅读和编辑的轨迹。它读取 Claude Code、Codex 和 pi 的会话日志（本地处理，不发送任何数据），将仓库渲染为树状或矩形树状图，并通过发光强度表示文件被触碰的深度和频率。工具提供播放控制、时间轴标记（上下文压缩、子代理启动、用户回合）、子代理镜头、文件历史检查器以及本地 LLM 评估功能。所有处理均在本地完成，唯一的例外是用户明确运行时才会发送会话摘要给本机 CLI 背后的模型。项目包含一个 Go 服务器和 React/Three.js 前端，通过命令行和浏览器交互。
Mindwalk 将会话日志（如 ~/.claude/projects 下的 JSONL）通过内部适配器（internal/adapter）归一化为有序的文件触碰事件流（trace），并同时关联子代理会话构建代理图。它通过 internal/citymap 为代码库生成确定性的 3D 布局（citymap），将深度和频率编码为发光强度。用户可通过 mindwalk serve 启动本地服务器并自动打开浏览器界面，或使用 mindwalk open <session.jsonl> 打开特定会话、mindwalk map <repo> 渲染仓库地图、mindwalk build 和 mindwalk trace 分别导出 citymap 和 trace 的 JSON。界面支持播放/暂停、速度调整、时间轴跳转、子代理镜头切换、文件点击查看访问历史，并可将回放导出为 .webm 视频。评估功能通过调用本机 claude 或 codex CLI，对会话进行四个固定维度和动态任务评分卡的评估，结果缓存在 ~/.mindwalk/reports。
- 开发者希望快速了解一个大型代码库中，编码代理是如何理解任务、在哪些文件上花费时间，从而评估其工作范围是否符合预期。
- 团队在审查代理生成的代码时，需要可视化代理的执行轨迹，以发现代理是否在无关文件上浪费了时间或忽略了关键部分。
- 在调试代理行为异常时，用户可以通过回放子代理的独立轨迹（agent lenses）来深入分析其决策过程。
- 技术经理或资深开发者需要对多个代理会话进行对比评估，利用一致的评分维度（探索、范围、漫游、验证）和任务特定标准来挑选最佳方案。
- 用户想要在没有会话数据的情况下浏览任意代码库的结构，通过
mindwalk map命令生成仓库的 3D 地图，利用高度表示代码行数。
如何安装或部署这个 Agent？
通过脚本安装：运行 curl -fsSL https://raw.githubusercontent.com/cosmtrek/mindwalk/master/scripts/install.sh | sh，然后设置 export PATH="$HOME/.local/bin:$PATH" 并启动 mindwalk。安装程序会验证校验和并安装到 ~/.local/bin（可通过 INSTALL_DIR 覆盖，VERSION 固定版本）。Windows 用户可从 GitHub Releases 下载。要求 Go 和 Node.js 环境。
如何使用这个 Agent？
直接运行 mindwalk 即可扫描默认目录（~/.claude/projects、~/.codex/sessions、~/.pi/agent/sessions），启动随机端口的 UI 并打开浏览器。常用命令：mindwalk serve --port N --no-open 指定端口；mindwalk open <session.jsonl> 打开特定会话；mindwalk map <repo> 打开仓库地图；mindwalk analyze <session> --judge claude|codex --model name 进行评估。在 UI 中，使用空格播放/暂停、方向键步进、S 调整速度、V 切换视图、E 跳转到下一个编辑、X 下一个错误、M 下一个标记、⌘B 显示会话栏。评估功能会在明确触发时调用本地 CLI，发送会话摘要给模型，并缓存报告。
这个 Agent 有哪些优点和局限？
- 完全本地处理：会话数据不离开机器，除了明确触发的评估（此时发送摘要给本机 CLI 背后的模型），隐私保护强。
- 直观的可视化：3D地图结合发光强度、触摸状态和播放控制，比阅读原始JSONL高效得多，能一眼看出代理的行为模式。
- 多代理支持：原生支持 Claude Code、Codex 和 pi 的会话日志，并可通过子代理镜头单独回放子代理轨迹。
- 可复现的比较：citymap 生成是确定性的，同一仓库始终生成相同地图，使得跨会话比较成为可能。
- 依赖外部代理工具：仅支持已记录的日志格式，对其他代理（如 Gemini、Cursor 等）需要额外适配。
- 安装要求：需要 Go 和 Node.js 环境，且安装脚本需要从网络下载二进制，可能受网络限制。
- 评估功能依赖本地安装的 claude 或 codex CLI，并且评估会消耗模型 API 额度。
- 学习曲线：可视化界面和命令较多，新用户需要一定时间熟悉。
这个 Agent 与同类方案有什么区别？
与相关度最高的同类 agent 并排比较关键指标。
| Agent | 源码审查 | 形态 / 费用 | Star | 最近更新 | 主语言 | 完整支持的平台 |
|---|---|---|---|---|---|---|
| Mindwalk - 代码库会话回放可视化 当前 | 59 · 缺口较多 | 命令行工具免费 + 模型费 | ★ 1.4k | 2 个月前 | Go | ChatGPT · Codex · Claude Code |
| Paseo | 49 · 缺口较多 | 桌面应用免费 + 模型费 | ★ 21k | 今天 | TypeScript | ChatGPT · Codex · Claude Code · OpenAI API |
| OpenCove 无限画布工作空间 | 46 · 缺口较多 | 桌面应用免费 | ★ 1.6k | 2 天前 | TypeScript | Codex · Claude Code |
| img2threejs — 代码重建三维模型 | 45 · 缺口较多 | Agent 插件 / 技能免费 + 模型费 | ★ 18k | 11 天前 | Python | Codex · Claude Code |
FollowAgents 如何评估这个 Agent？
查看各维度的扣分理由
证据显示：工具默认本地运行，仅当用户明确运行评估时才发送会话摘要到本地CLI；安装脚本校验checksums；无网络请求。扣分：依赖仅一个jsonschema库，但未提供依赖漏洞扫描或锁定文件细节；回滚机制未明确；发布者身份未验证。
证据显示：README描述与代码结构一致，有CI测试和前端构建验证；依赖为Go标准库和少量第三方，可用性高。扣分：失败消息未在文档中详细说明，错误处理细节未展示。
证据显示：面向开发者，支持多种agent格式和平台（Linux、macOS、Windows、Nix）；能力边界清晰（只读会话日志，评估需显式调用）；触发条件明确（命令行参数）。扣分：环境适配细节（如特定shell、权限）未完全说明。
证据显示：README结构清晰，安装说明详细，命名稳定（命令和参数一致），有示例和FAQ（通过文档和截图），MIT许可证明确。扣分：已知限制未明确列出，版本变更日志未提供，维护责任未明确（发布者未验证）。
证据显示：输出为可视化界面和JSON文件，可直接使用；边际价值高（解决会话理解问题）；成本低（本地运行，免费）。扣分：无成本效益分析，但整体合理。
证据显示：README中的声明与代码结构一致，有测试和CI；文档区分事实和推断（如评估报告）。扣分：跨来源验证不足（仅单一仓库证据）。
- 发布者身份未验证，安装脚本从远程获取，建议检查校验和。
- 评估功能会发送会话摘要到本地CLI，确保理解数据流向。
- 依赖较少，但未提供依赖漏洞扫描，建议定期检查。
最近版本
来自该项目 GitHub Releases 的最新发布记录，说明为上游原文摘录，未经本站改写或测试。
-
发布说明摘录
Changelog * 68aeda671a48eb6e406792e984d3570f28dc5e70 Tip for Nix users (#24) * a3569baa875d8c5f8fde2e7c93896f99af39c029 server: component boundaries — traceStore, adapter sidecar interface, report index, loopback hardening (#23) * 9a262e25d9024c8433fc670d6e7491c7bedf5b12 feat(citymap): bounded adaptive scanning for oversized session roots (#22)在 GitHub 查看 ↗ -
发布说明摘录
Changelog * b3b98a033ebc5eddc286efe4549b08d87d95aba9 feat(adapter): support pi sessions (#20) * e49e9e672dfe29c570b5b44d3f523f4ca0760083 fix: update star history chart links in README * 7721e6e964676b8b2204e2e8d8fd67d318969833 feat: task-rubric layer for session evaluation (#19) * e208b6b8504138843f671e031f28129b66003a67 docs: update demo video made by kimi k3 * 3f614a90a7a77c3ab14ba7f2c4c7bbd057b762d5 chore: remove obsolete demo video ignore在 GitHub 查看 ↗ -
发布说明摘录
Changelog * b9c12798d012f8600d015a429a1ed7f9cdef4f69 docs: fix asset URL in README.md * 81b408abc48566e26f2e58aa7f8d3dc9a65fa72f docs: update demo link * e0ae880b84c517e111b58470f6585f5a22b0c61a docs: refresh README screenshots and feature notes * 823e862499416cf5c6e97523a18868220590ee3f fix(adapter): show nested Codex exec summaries * 05081bcb4ac9bb7afb89f756d2721988f9c4ebaa feat: add Agent Lens for subagent traces (#12) * 8a28839f5b0dd6bc64401af226508068a70037ae fix: centralize UTF-8-safe truncation * 6e8c7883f1df6fb312ad8872c435672037b795df fix: preserve UTF-8 in judge errors (#13) …在 GitHub 查看 ↗