Mindwalk: Visualizing AI Coding-Agent Sessions in 3D

Mindwalk: Visualizing AI Coding-Agent Sessions in 3D

Mindwalk provides a spatial method for auditing AI coding agents by replaying session logs on a 3D map of a repository. While standard session logs record what an agent did, Mindwalk visualizes how the agent understood the task—specifically which files it treated as relevant and where it explored before acting.

Spatial Analysis of Agent Behavior

Mindwalk transforms a repository into a "night map" where the agent's activity creates light. This allows developers to see the agent's footprint at a glance, determining if the agent's exploration matched the intended scope of the task.

Visualization Modes and Indicators

  • Tree and Terrain Views: The codebase is represented as either a radial tree or a treemap plain. The intensity of the glow indicates how deeply and frequently a file was touched.
  • Touch States: Files are color-coded based on their deepest interaction:
    • Moss Green: Seen
    • Moon White: Read
    • Warm Amber: Edited
    • Dark: Unvisited
  • Playback Deck: A bucketed histogram allows users to scrub through the session. Observation phases (search, read, exec) are indicated by cool colors, while mutation phases (edit, verify) glow warm.
  • Timeline Marks: Specific symbols mark key events: ◇ for context compactions, ○ for subagent launches, and › for user turns.

Technical Architecture

Mindwalk is built as a local Go binary that ensures no session data leaves the user's machine. It separates the data into two distinct artifacts:

  1. The Trace: A normalized stream of file-touch events derived from session logs via adapters. It currently supports Claude Code and Codex session logs.
  2. The Citymap: A deterministic layout of the repository. Because the same tree always produces the same map, replays can be compared across different sessions.

The system uses a local Go server to join the trace and citymap, serving a frontend built with React and Three.js.

Installation and Usage

Mindwalk can be installed via a shell script or built from source using a Makefile.

Quick Start:

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

Core Commands:

  • mindwalk serve: Scans ~/.claude/projects and ~/.codex/sessions and serves the UI on a local port.
  • mindwalk open <session.jsonl>: Opens a specific session log.
  • mindwalk build <repo>: Generates the repository citymap JSON.
  • mindwalk trace <session>: Writes the normalized trace JSON.

Community Insights and Use Cases

While some users questioned the immediate utility of 3D visualization over traditional diffs, others highlighted potential high-value use cases for spatial agent auditing:

"One I think might be cool is some kind of spatial/represented comparison: let's see how two different models interact with the codebase (for the same problem), what they touched, and what they did."

Other community members noted that terminal-based "Read file" logs are often difficult to follow, and a spatial representation makes it easier to identify exactly where an LLM is sourcing its information. Some users suggested extending the tool to provide a cumulative history across all agents rather than per-session history.

Sources