Dev ToolsArticle A local Go tool turns Claude Code and Codex session logs into 3D codebase replays you can scrub and audit.
Lenn Voss Coding agents leave a trail. They search, read, edit, run tools, spawn subagents, and compact context. What they rarely leave is a legible picture of how they understood the job. Session logs are JSONL dumps: ordered events, file paths, tool calls. Useful if you already know what you are looking for. Useless if you want a fast answer to a simpler question: did this agent stay inside the blast radius you expected?
Mindwalk is an early answer to that question. It takes Claude Code and Codex session logs, builds a deterministic 3D layout of your repo, and replays the run as light moving across a dark map. Files the agent touched glow. Everything else stays black. The result is not a prettier log viewer. It is a spatial audit of the agent's mental model of your tree.
That distinction matters more than the Three.js polish.
The gap logs never closed #
Agent harnesses already give you multi-turn history, tool approvals, and the usual "diff what changed" review. Those are necessary and still incomplete. A diff shows outcome. A raw session log shows sequence. Neither shows scope of attention: which corners of the repo the model treated as relevant before it wrote anything, how often it re-read a file, whether it wandered into unrelated packages, or whether edits kept happening after the last verify step.
That gap gets worse as agents get more autonomous. Modern coding agents read and write files, run shell commands, and iterate on type-checker or test failures without constant hand-holding. Teams are also packaging repo-wide guidance in files like AGENTS.md
so each session starts with shared conventions instead of a retyped prompt. Guidance helps. It does not tell you whether a given run actually respected the structure you thought you were giving it.
Mindwalk's bet is visual: if you can see the footprint as a shape, mismatches jump out. A tight glow around src/auth/
looks different from a scatter of amber edits across half the monorepo.
How the map is built #
The tool keeps two artifacts deliberately separate.
A citymap is a deterministic layout of the repository. Same tree, same map. That stability is the point: two sessions on the same repo become comparable instead of two unrelated force-directed scribbles.
A trace is the session log normalized into an ordered stream of file-touch events. Adapters sit in front of Claude Code and Codex formats so the rest of the pipeline does not care which agent produced the JSONL.
A local Go server joins the two and serves a React / Three.js UI. Nothing about the session is supposed to leave the machine. One binary covers install, serve, and export paths. With no args it scans the usual Claude and Codex session directories, picks a local port, and opens a browser. You can also point it at a single session.jsonl
, or export the citymap and trace JSON yourself for tooling that is not the UI.
On the map, each file keeps its deepest touch state:
seen(moss green)** read**(moon white)** edited**(warm amber)** unvisited**(dark) Tree and terrain views give you a radial tree or a treemap plain. Glow scales with how deeply and how often a path was hit. Playback sits on a bucketed histogram of the run: cool bars for observation (search, read, exec), warm bars for mutation (edit, verify). Timeline marks call out context compactions, subagent launches, and user turns as click-to-jump targets. An inspector pins a file's visit history and jumps the playhead to a specific moment.
Keyboard shortcuts cover the usual scrubber needs: , step, speed, next edit, next error, next mark. The HUD folds friction signals (error rate, churned files, edits after the last verify) into a review strip so you are not only watching pretty lights.
What this is actually for #
This is not a daily driver for "write a function." It is a post-hoc instrument for runs that already happened, especially ones that touched more files than you want to reconstruct from a diff alone.
Concrete cases where it earns its keep:
Scope audits. You asked for a narrow fix. The map shows whether the agent treated half the package as relevant. That is a different signal than "the PR is large."Review of long agent sessions. Multi-turn runs with subagents and context compactions are hard to reconstruct from JSONL. Timeline marks and the histogram make phase structure visible: exploration vs. thrash vs. verify loops.Comparing sessions on the same repo. Because the citymap is deterministic, you can ask whether two approaches to the same task left similar footprints, not just similar diffs.Teaching and onboarding. Showing a junior (or a skeptical teammate)wherean agent spent attention is faster than walking them through tool-call transcripts.
What it does not replace: code review, tests, type-checkers, or your own judgment about whether a change is correct. A clean amber path through the right modules can still be a wrong design. Mindwalk visualizes attention and mutation, not correctness.
Practical trade-offs for developers #
Adoption is low-friction if you already use Claude Code or Codex locally. Install is a checksum-verified script into ~/.local/bin
(or a release archive on Windows; or make setup && make build
from source). Then either mindwalk
with no args or mindwalk open path/to/session.jsonl
.
Caveats worth knowing before you plan a workflow around it:
Agent coverage is narrow. Claude Code and Codex only, via format-specific adapters. Cursor, Aider, Copilot cloud agents, and custom harnesses are outside the box until someone writes adapters that emit the same touch-event stream.
It is early software. Public repo metrics put it in Show HN territory (on the order of a hundred-plus stars, single-digit forks, v0.1.0). Expect sharp edges, not a polished product surface.
Local-only is a feature and a constraint. Session data stays on your machine, which is the right default for private code. It also means no shared team dashboard unless you export artifacts and build that layer yourself. The schema and export commands (mindwalk build
, mindwalk trace
) exist for that kind of extension.
Visualization can lie by omission. Files never opened stay dark. That is the point of the night map, but it can also hide why the agent never looked somewhere (missing instructions, bad search, overconfident first hit). Pair the map with the inspector and the actual session marks, not vibes alone.
Performance and map quality scale with repo shape. A deterministic layout of a huge monorepo is still a layout of a huge monorepo. The interesting signal is relative glow and phase structure, not pixel-perfect geography.
If you want to experiment without changing how you work day to day: keep using your agent as usual, then open a few recent sessions after a messy multi-file change. Ask one question only: does the glowing region match the task you thought you assigned? That is enough to decide whether the tool belongs in your review loop.
Early, specific, and pointed the right way #
Mindwalk is not "AI code review" and it is not a general observability platform. It is a focused instrument for a real failure mode: agents that act with a hidden map of your repo while you only see the final patch.
As agent sessions get longer, more tool-heavy, and more often guided by shared AGENTS.md
-style context, the need for something like this grows. The open question is not whether 3D trees are cool. It is whether spatial replays become a standard artifact next to the diff, the test log, and the session transcript. Mindwalk is one of the first tools that treats that as a first-class problem and keeps the data local while it does so.
Worth installing if you already run Claude Code or Codex on real repos. Worth watching if you care about agent auditability more than another chat UI. Not yet something to mandate for a whole org. The idea, though, is the right shape for where agent workflows are headed.
Sources & further reading #
[Show HN: Mindwalk – Replay coding-agent sessions on a 3D map of your codebase](https://github.com/cosmtrek/mindwalk)— github.com -
[The Brutalist Report - tech](https://brutalist.report/topic/tech)— brutalist.report -
[AGENTS.md and SKILL.md: building a reusable agent toolbox | Chris Reddington](https://chrisreddington.com/blog/building-your-agent-toolbox/)— chrisreddington.com -
[Agentic Coding · Missing Semester](https://missing.csail.mit.edu/2026/agentic-coding/)— missing.csail.mit.edu
[Lenn Voss](https://sourcefeed.dev/u/lennart_voss)· Cloud & Infrastructure Writer
Lenn writes about cloud platforms, Kubernetes internals, and the infrastructure decisions that quietly make or break engineering organizations. Based in Berlin's vibrant tech scene, they have a talent for turning dense platform-engineering topics into prose that people actually finish reading.
Discussion 0 #
No comments yet
Be the first to weigh in.