Mindwalk: Visualizing AI Coding Agent Sessions in 3D

Mindwalk provides spatial visibility into AI agent reasoning

Mindwalk is a visualization tool designed to solve the "black box" problem of AI coding agents. While standard session logs (JSONL) record what an agent did, they fail to convey how the agent understood the task—specifically which files it deemed relevant, where it explored before acting, and whether its footprint aligned with the intended scope. Mindwalk transforms these logs into a 3D "night map" of the repository, where agent activity is represented as light moving through the codebase.

Core Visualization Features

Mindwalk translates abstract session logs into visual shapes and colors to make agent behavior instantly recognizable.

Terrain and Tree Views

Users can toggle between two primary perspectives of the repository:

Tree View: A radial representation of the codebase.
Terrain View: A treemap-style plain.

In both views, the "glow" of a file is proportional to how deeply and frequently the agent touched that specific file.

Touch States and Color Coding

To differentiate between types of interaction, Mindwalk assigns specific colors to file states based on the deepest level of interaction:

Moss Green: Seen
Moon White: Read
Warm Amber: Edited
Dark: Unvisited

Playback and Timeline Analysis

The tool includes a playback deck with a bucketed histogram of the run. The histogram uses a temperature spectrum to categorize actions:

Cool Spectrum: Observation phases (searching, reading, executing).
Warm Spectrum: Mutation phases (editing, verifying).

Timeline marks allow users to jump directly to specific events, such as context compactions (◇), subagent launches (○), and user turns (›).

Technical Architecture

Mindwalk is built as a local Go binary that ensures no session data leaves the user's machine. The system is split into two distinct artifacts to ensure comparability across different sessions:

The Trace: A normalized stream of file-touch events generated by adapters for specific agent formats (currently supporting Claude Code and Codex).
The Citymap: A deterministic layout of the repository. Because the same tree always produces the same map, developers can compare the "shape" of different agent sessions on the same codebase.

The backend is a local Go server that joins the trace and citymap, serving a frontend built with React and Three.js.

Installation and Usage

Mindwalk can be installed via a shell script:

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

By default, the tool scans ~/.claude/projects and ~/.codex/sessions to serve the UI on a local port. It also provides CLI commands for specific tasks:

mindwalk open <session.jsonl>: Opens a specific session.
mindwalk build <repo>: Generates a repository citymap JSON.
mindwalk trace <session>: Generates a normalized trace JSON.

Community Perspectives and Use Cases

While some users questioned the immediate utility of a 3D visualizer over traditional diffs, others identified high-value technical use cases for spatial agent analysis.

Potential Applications

Model Comparison: Comparing how two different LLMs interact with the same codebase to solve the same problem.
Variance Analysis: Averaging 100 runs of the same model to identify the most common paths and the variance in agent behavior per task.
Performance Diagnostics: Using spatial traces to identify "hot paths" or inefficient exploration patterns in agent reasoning.

User Feedback

Community members noted that terminal-based logs (e.g., "Read file: xyz") are difficult to follow, and a spatial representation makes the source of the LLM's information more obvious. One user noted:

"I’m becoming convinced the optimal UI to engage with agents, long term is going to be something spatial."

However, some users cautioned that 3D interfaces can introduce friction if they do not provide a more efficient way of scanning changes than existing ergonomic tools.