Mindwalk: Replay Claude Code/Codex sessions as light trails on a 3D code map

Mindwalk is a visualization tool that replays coding-agent sessions on a 3D map of your codebase. Instead of staring at raw JSONL session logs, you get a night map where light moves as the agent searches, reads, and edits — untouched parts stay dark.

What it solves

A session log tells you what an agent did, but not how it understood the task: which parts of the repo it treated as relevant, where it explored before acting, or whether its footprint matched your intent. Reading JSONL line by line doesn't answer that.

Quick start

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

The installer verifies the binary against checksums.txt and installs to ~/.local/bin (override with INSTALL_DIR; pin a release with VERSION). Windows archives are on GitHub Releases. To build from source: make setup && make build → bin/mindwalk.

Commands

With no arguments, mindwalk scans ~/.claude/projects and ~/.codex/sessions, serves the UI on a random local port, and opens a browser:

• mindwalk serve [--port N] [--no-open] [--claude-dir DIR] [--codex-dir DIR]
• mindwalk open [--no-open] <session.jsonl> — open one specific session
• mindwalk build <repo> [-o out] — write the repository citymap JSON
• mindwalk trace <session> [-o out] — write the normalized trace JSON

Reading the visualization

• Tree / Terrain views — the repo as a radial tree or treemap; glow intensity ∝ how deeply and often a file was touched.
• Touch states — each file keeps its deepest touch: seen (moss green), read (moon white), edited (warm amber), unvisited (dark).
• HUD folds friction signals — error rate, churned files, edits after the last verify — into a review strip.
• Playback deck — scrub or play over a bucketed histogram. Bars on a cool/warm spectrum: observation (search, read, exec) stays cool, mutation (edit, verify) glows warm.
• Timeline marks — ◇ context compactions, ○ subagent launches, › user turns; click to jump.
• Inspector — click a file to pin its visit history; click a visit row to jump the playhead.
• Keyboard: Space play/pause · ←/→ step (⇧×10) · Home/End ends · S speed · E next edit · X next error · M next mark · ⌘B session rail.

Under the hood

Two separate artifacts: a trace (normalized stream of file-touch events from session logs via adapters in internal/adapter) and a citymap (deterministic layout of the repository in internal/citymap). A local Go server (internal/server) joins them and serves the React/Three.js frontend (web). Schema contracts live in schema/.

The same tree always produces the same map, so replays are comparable across sessions. No session data leaves your machine — fully local.