mindwalk

mindwalk is an open-source CLI tool built in Go that turns raw coding-agent session logs into an interactive 3D visualization of your repository. Created by Ricko Yu and released under the MIT license, it reads Claude Code and Codex session logs locally — no data leaves your machine during viewing — and renders the agent's activity as light moving through a night-map of your codebase.

What It Is

mindwalk sits in the category of developer observability and agent-session analysis tools. Its core job is to answer a question that raw JSONL logs cannot: not just what a coding agent did, but how it understood the task — which parts of the repo it treated as relevant, where it explored before acting, and whether its footprint matched the intended scope. The tool produces a local web UI backed by a Go server serving a React/Three.js frontend, all packaged as a single binary.

How the Visualization Works

The repository is drawn as a "night map" and the session plays back as light moving through it. Three visual modes and several interactive layers make the session readable at a glance:

• Tree / Terrain views — the repo rendered as a radial tree or a treemap plain; glow intensity reflects how deeply and how often a file was touched.
• Touch states — each file holds its deepest touch: seen (moss green), read (moon white), edited (warm amber), unvisited (dark).
• Playback deck — a bucketed histogram of the run on a cool/warm spectrum; observation events (search, read, exec) stay cool, mutation events (edit, verify) glow warm.
• Timeline marks — context compactions (◇), subagent launches (○), and user turns (›) are all click-to-jump targets.
• Inspector — click any file to pin its visit history and jump the playhead to any moment.

Keyboard shortcuts cover play/pause, stepping, speed, and jumping to the next edit, error, or mark.

Architecture: Three Deliberate Artifacts

The README describes three artifacts kept intentionally separate to ensure replays are comparable across sessions:

1. Trace — the session log normalized into an ordered stream of file-touch events, with one adapter per agent format (internal/adapter).
2. Citymap — a deterministic layout of the repository (internal/citymap); the same tree always produces the same map.
3. Report — an LLM judge's evidence-anchored findings about one session (internal/judge); verdicts are rolled up mechanically so reports stay comparable.

A local Go server joins these artifacts and serves the React/Three.js frontend. JSON contracts are mirrored in schema/.

Session Evaluation and Privacy Model

An optional evaluate panel (also accessible via mindwalk analyze) asks a locally installed agent CLI — Claude Code or Codex — to judge the session's trajectory across dimensions like exploration, scope, wandering, and verification. Every finding is anchored to timeline events that are clickable in the UI. The privacy boundary is explicit: evaluation sends only the session's user-message wording, file paths, and one-line event digests to the model behind the user's own CLI account. Nothing is sent during passive viewing. The judge subprocess runs sealed with no tools, no MCP servers, and no session persistence. Reports are cached in ~/.mindwalk/reports and go stale only when session content changes.

Update: v0.1.0

The first release, v0.1.0, was published on July 11, 2026, roughly two days after the repository was created on July 9, 2026. The project accumulated 580 stars and 33 forks within about a week of creation, signaling strong early interest from the developer community. Installation is via a shell script that verifies the binary against checksums.txt and places it in ~/.local/bin; Windows archives are available on GitHub Releases. Building from source requires make setup && make build.