Mindwalk: A 3D Visualization Tool for AI Coding Agent Sessions
AI coding agents have made it possible to ship features and refactors that would have taken days in a matter of hours. The tradeoff is opacity. When Claude Code or Codex finishes a task, you're left with a transcript of actions and a git diff. The transcript tells you what the agent did. The diff shows you the result. Neither tells you how the agent understood your codebase, where it wandered, or whether its exploration was thorough before it started making changes.
Mindwalk, released by Ricko Yu in July 2026 under the MIT license, addresses this by replaying agent sessions as an interactive 3D visualization. Your codebase becomes a city. The agent's path through it becomes visible. This article covers how to install it, how to read the visualization, and how to use the analyze command to audit agent behavior.
The problem Mindwalk solves
A typical agent session log looks like this:
This is a factual record, not an explanation. It tells you what the agent touched but nothing about the reasoning behind the sequence. Critical questions go unanswered: did the agent read enough context before changing things? Did it stay within the scope of the task, or did it explore unrelated modules? Did it verify its changes? For a small bug fix, this doesn't matter much. For a refactor touching dozens of files, it matters considerably.
Installation
Mindwalk is a single Go binary that serves a React and Three.js frontend. No session data leaves your machine.
Install with:
The installer verifies the binary against checksums before installing to ~/.local/bin. You can override the install directory with INSTALL_DIR or pin a specific release with VERSION. Windows archives are available on the GitHub releases page. To build from source: make setup && make build.
Launching a session replay
Navigate to the root of the project where the agent session was run and start Mindwalk:
Mindwalk starts a local web server and opens a browser tab automatically. The URL will be something like http://127.0.0.1:56843. All processing happens locally.
The 3D visualization
The city metaphor
Every file in your repository is a building. Building height is proportional to lines of code.
This gives you an immediate architectural overview before the replay begins. Large configuration files and core utilities stand out as skyscrapers; small components are low-rise. Directories cluster visually, so the project's module structure becomes legible at a glance.
Color coding
Mindwalk uses color to communicate what the agent did to each file. The key distinction is between looking and changing.
The specific colors:
- Moss green: The agent glanced at this file, such as listing directory contents or a superficial scan
- Moon white: The agent read the file's contents in depth, loading it into context
- Amber/orange: The agent edited this file
- Dark/unlit: The agent never touched this file
Files are colored by their deepest touch state during the session, so you can see at a glance which parts of the codebase the agent actually engaged with versus what it ignored entirely.
Timeline and keyboard shortcuts
The timeline at the bottom of the screen marks the full sequence of agent actions. Click anywhere to jump to that moment; drag the playhead to scrub through the session. Keyboard shortcuts: Space to play/pause, ←/→ to step (hold ⇧ for ×10 jumps), Home/End to jump to start or end, E for next edit, X for next error, M for next mark.
Timeline event markers
The timeline is also marked with symbols for critical events in the agent's lifecycle.
The three key markers are subagent spawned (when the main agent delegates a subtask), context window compacted (when the agent had to compress its memory to make room for new context, which can cause information loss), and user input (when you intervened with a new instruction). These events are easy to miss in a flat transcript but become significant in the spatial replay.
Standalone repo map
You can also render your codebase as a city without any session attached, using mindwalk map <repo>. In this mode, building height still encodes lines of code and gives you a pure architectural overview of the project.
Auditing agent behavior with mindwalk analyze
The replay shows you where the agent went. The analyze command evaluates whether it went to the right places.
The --judge flag accepts any installed CLI: claude, codex, or a local model via Ollama. The judge reads the normalized session trace, not your actual code, and evaluates the agent's methodology across three dimensions:
- Exploration: Did the agent read enough relevant context before making changes?
- Scope: Did the agent stay focused on the task, or did it wander into unrelated parts of the codebase?
- Verification: Did the agent run tests or other checks after making changes?
The output is a JSON report with claims, verdicts, and evidence. Each finding links to the exact moment on the Mindwalk timeline, so you can click through to investigate anything the judge flags. Reports are cached in ~/.mindwalk/reports and go stale when the session content changes but never auto-rerun.
The evaluation panel is also accessible in the UI itself, not just the CLI. You pick the judge and its model in the panel; the report records which judge was used.
What leaves your machine
Mindwalk itself reads logs locally and sends nothing externally. When you run analyze, the judge CLI sends a summary to whichever model you've configured under your own account: user message wording, file paths, and one-line event digests. Actual code content doesn't leave your machine.
When it's worth using
For a two-line bug fix, Mindwalk is overkill. A plain git diff is faster and more informative for simple changes. Mindwalk's Hacker News launch thread acknowledged this directly.
The tool earns its place in three scenarios:
For model comparison and research, Mindwalk lets you run the same task with different models and compare their exploration patterns visually. You can see whether one model reads more context before editing, whether it stays on-task better, or whether it consistently verifies changes.
For large-scale refactors, when an agent touches dozens of files across a pull request, the 3D flythrough combined with the analyze report gives you a narrative of the change in minutes. That narrative would take much longer to piece together from a flat diff alone.
For debugging failed sessions, Mindwalk acts as a flight recorder. If an agent went off the rails, you can scrub back through the replay to find the moment its reasoning diverged from what you intended, which gives you concrete data for refining your prompts or the agent's configuration.
The project is on GitHub and is actively maintained. The architecture is modular: trace adapters, citymap generation, and the React/Three.js frontend are kept separate, which makes it straightforward to add support for additional agent frameworks beyond Claude Code and Codex.
This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.