Show HN: Mindwalk – Replay coding-agent sessions on a 3D map of your codebase

mindwalk A visualization tool that replays coding-agent sessions on a 3D map of your codebase. mindwalk-demo.mp4 The 30-second demo — sound on.

mindwalk 一个可视化工具，可以在代码库的 3D 地图上回放编码代理（coding-agent）的会话过程。 mindwalk-demo.mp4 30 秒演示视频 —— 请开启声音。

The problem

A session log records what an agent did, but not how it understood the task: which parts of the repo it treated as relevant, where it explored before it acted, whether its footprint matched the scope you had in mind. Reading the raw JSONL line by line doesn’t answer any of that.

问题所在

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

The idea

Draw the repository as a night map, and play the session back as light moving through it: where the agent searched, read, and edited, the map glows — everything else stays dark. The agent’s understanding of the task becomes a shape you can see at a glance.

核心理念

将代码库绘制成一张夜间地图，并将会话过程以光线穿梭的形式回放：代理搜索、阅读和编辑过的地方，地图会发光——其余部分则保持黑暗。代理对任务的理解变成了一种你可以一眼看清的形状。

One Go binary reads Claude Code and Codex session logs, fully local; no session data leaves your machine.

单个 Go 二进制文件即可读取 Claude Code 和 Codex 的会话日志，完全本地化；没有任何会话数据会离开你的机器。

Quick start

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

The installer verifies the binary against checksums.txt and installs to ~/.local/bin (override with INSTALL_DIR; pin a release with VERSION). Windows archives are on GitHub Releases. To build from source: make setup && make build → bin/mindwalk.

快速开始

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。

With no arguments, mindwalk scans ~/.claude/projects and ~/.codex/sessions, serves the UI on a random local port, and opens a browser:

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)

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

mindwalk serve [--port N] [--no-open] [--claude-dir DIR] [--codex-dir DIR]
mindwalk open [--no-open] <session.jsonl>（打开指定的单个会话）
mindwalk build <repo> [-o out]（生成代码库的 citymap JSON）
mindwalk trace <session> [-o out]（生成标准化的 trace JSON）

Reading the picture

Tree / Terrain views — the repo as a radial tree or a treemap plain; glow ∝ how deeply and how often a file was touched.
Touch states — each file keeps its deepest touch: seen (moss green), read (moon white), edited (warm amber), unvisited (dark).
The HUD folds friction signals — error rate, churned files, edits after the last verify — into a review strip.
Playback deck — scrub or play the session over a bucketed histogram of the run. Bars sit on a cool/warm spectrum: observation stays cool (search, read, exec), mutation glows warm (edit, verify), so editing phases jump out at a glance.
Timeline marks — ◇ context compactions, ○ subagent launches, › user turns; every mark is a click-to-jump target.
Inspector — click a file to pin its visit history; click a visit row to jump the playhead to that moment.

解读画面

树状/地形视图 — 将代码库呈现为径向树或矩形树图；发光程度与文件被触及的深度和频率成正比。
触及状态 — 每个文件保留其最深层的触及状态：已查看（苔藓绿）、已阅读（月光白）、已编辑（暖琥珀色）、未访问（暗色）。
HUD（平视显示器） — 将摩擦信号（错误率、文件变动、最后一次验证后的编辑）整合进一个审查条中。
回放控制台 — 在运行过程的柱状直方图上拖动或播放会话。柱状图采用冷/暖色谱：观察阶段保持冷色（搜索、阅读、执行），修改阶段呈现暖色（编辑、验证），因此编辑阶段一眼即可识别。
时间轴标记 — ◇ 上下文压缩，○ 子代理启动，› 用户交互；每个标记都是一个可点击跳转的目标。
检查器 — 点击文件以固定其访问历史；点击访问行可将播放头跳转到该时刻。

Keyboard: Space play/pause · ←/→ step (⇧ ×10) · Home/End ends · S speed · E next edit · X next error · M next mark · ⌘B session rail.

键盘快捷键： 空格键播放/暂停 · ←/→ 单步（⇧ ×10） · Home/End 结尾 · S 速度 · E 下一个编辑 · X 下一个错误 · M 下一个标记 · ⌘B 会话栏。

Under the hood

Two artifacts, kept deliberately separate:

a trace — the session log normalized into an ordered stream of file-touch events (internal/adapter, one adapter per agent format);
a citymap — a deterministic layout of the repository (internal/citymap); the same tree always produces the same map, so replays are comparable across sessions. A local Go server (internal/server) joins the two and serves the React/Three.js frontend (web). schema/ mirrors the exported JSON contracts.

技术内幕

两个工件被刻意分开：

trace（追踪） — 将会话日志标准化为有序的文件触及事件流（internal/adapter，每种代理格式对应一个适配器）；
citymap（城市地图） — 代码库的确定性布局（internal/citymap）；相同的树结构总是生成相同的地图，因此不同会话之间的回放具有可比性。本地 Go 服务器（internal/server）将两者结合，并提供 React/Three.js 前端（web）。schema/ 目录镜像了导出的 JSON 契约。

Contributing

Issues and pull requests are welcome. To get a working dev setup:

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

贡献

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

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

Ground rules (see AGENTS.md for the full architecture notes): Keep the boundaries: adapters don’t know about rendering, citymap generation doesn’t depend on playback, the server just connects the two. Keep Go code gofmt-ed; never hand-edit internal/server/static — regenerate it with make build. When trace or citymap JSON shapes change, update schema/ and the relevant tests in the same change.

基本原则（完整架构说明请参阅 AGENTS.md）：保持边界清晰：适配器不了解渲染逻辑，城市地图生成不依赖于回放，服务器仅负责连接两者。保持 Go 代码符合 gofmt 规范；切勿手动编辑 internal/server/static — 请使用 make build 重新生成。当 trace 或 citymap 的 JSON 结构发生变化时，请在同一次变更中更新 schema/ 和相关测试。