Mindwalk: Visualizing Agentic Coding Journeys

Mindwalk is a specialized visualization utility designed to replay the sessions of coding agents across a three-dimensional representation of your project's architecture.

🚩 The Problem

Standard session logs provide a chronological record of what an agent executed, but they fail to convey the agent's mental model of the task. Specifically, raw logs don't easily reveal:

• Which files the agent deemed relevant.
• The path of exploration taken before a change was made.
• Whether the agent's actual footprint aligned with the intended scope.

Reading raw JSONL files line-by-line is an inefficient way to answer these questions.

💡 The Concept

Imagine your codebase as a city map at night. As the session replays, the agent's activity acts as a light source moving through the streets:

• Glow: Areas where the agent searches, reads, or modifies light up.
• Darkness: Untouched files remain dark.

This transforms the agent's cognitive process into a visible, geometric shape.

Privacy First: Mindwalk is a single Go binary that processes Claude Code and Codex logs entirely on your local machine. No data is transmitted externally.

---

🚀 Getting Started

Installation

You can install Mindwalk using the following command:

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

• Verification: The installer checks the binary against checksums.txt.
• Customization: Use INSTALL_DIR to change the path or VERSION to pin a specific release.

Usage

• Automatic Mode: Run mindwalk to scan ~/.claude/projects and ~/.codex/sessions, launch a local server on a random port, and open your browser.

Command Reference

---

👁️ Interpreting the Visualization

Terrain & Lighting

Users can toggle between Tree and Terrain views (radial tree or treemap). The intensity of the light is defined by: $\text{glow} \propto \text{depth and frequency of file access}$

Touch State Color Palette:

• <span style="color: #8a9a5b">■</span> Moss Green: Seen
• <span style="color: #f0f8ff">■</span> Moon White: Read
• <span style="color: #ffbf00">■</span> Warm Amber: Edited
• <span style="color: #2f4f4f">■</span> Dark: Unvisited

The Interface (HUD)

• Review Strip: Aggregates "friction signals" such as churned files, error rates, and edits performed after the final verification.
• Playback Deck: A bucketed histogram of the run.
  • Cool Spectrum: Observation (searching, reading, executing).
  • Warm Spectrum: Mutation (editing, verifying).
• Timeline Markers:
  • $\diamond$ Context compactions
  • $\circ$ Subagent launches
  • $\text{>}$ User turns
• Inspector: Pin a file to view its specific visit history or click a visit row to jump the playhead.

⌨️ Keyboard Shortcuts

Space Play/Pause $\cdot$ ← / → Step ($\text{Shift} \times 10$) $\cdot$ Home / End Jump to ends $\cdot$ S Speed $\cdot$ E Next edit $\cdot$ X Next error $\cdot$ M Next mark $\cdot$ ⌘B Session rail.

---

⚙️ Under the Hood

Mindwalk separates the session data from the structural data:

1. The Trace: A normalized stream of file-touch events created via internal/adapter.
2. The Citymap: A deterministic layout of the repository (internal/citymap). Because the layout is deterministic, different sessions can be compared accurately.
3. The Server: A local Go server (internal/server) that bridges the data to the web frontend.

Development Workflow

To set up a development environment:

make setup  # Install frontend deps
make serve  # Start dev server on :8765
make test   # Run Go tests and frontend build
make build  # Embed assets and create bin/mindwalk

Ground Rules

• Strict Boundaries: Adapters should not handle rendering; citymap generation must be independent of playback.
• Code Style: Go code must be gofmt -ed. Do not manually edit internal/server/static.
• Schema: Any changes to trace or citymap JSON must be reflected in schema/ and accompanying tests.

---

License: MIT $\cdot$ © 2026 Ricko Yu Tech Stack: Go (47.6%), TypeScript (42.3%), CSS (8.2%), HTML (1.2%)