mindwalk

mindwalk replays a coding-agent session as light moving across a 3D map of your codebase. It reads Claude Code and Codex session logs, draws the repository as a dark night map, and plays the run back: the files the agent searched, read, and edited glow, everything it ignored stays dark. The point is to see the shape of what the agent understood as the task — which parts of the repo it treated as relevant, where it explored before acting, whether its footprint matched the scope you had in mind. A raw JSONL log records the same events but answers none of that at a glance. Author Ricko Yu (cosmtrek, of air live-reload fame) says the original motivation was comparing how different LLMs solve a task by looking at the trajectory rather than the diff.

How it works

The design keeps three artifacts deliberately separate, each in its own package:

• A trace is the session log normalized into an ordered stream of file-touch events. One adapter per agent format lives in internal/adapter; adapters also correlate subagent sessions into an agent graph, so each subagent's trace can be replayed on its own.
• A citymap is a deterministic layout of the repository (internal/citymap). The same tree always produces the same map, so replays of different sessions over the same repo line up and can be compared.
• A report is an LLM judge's evidence-anchored findings about one session (internal/judge). The judge only contributes findings; verdicts are always rolled up mechanically, so reports stay comparable across sessions too.

A local Go server (internal/server) joins the three and serves a React/Three.js frontend. The whole thing ships as one Go binary with the frontend embedded, and viewing is fully local — nothing leaves the machine while you watch a session.

Files carry a "deepest touch" state rendered as color: seen is moss green, read is moonlight blue, edited is warm amber, unvisited stays dark. Files the session touched but that no longer exist in the repo linger as wireframe ghosts. A playback deck scrubs the run over a histogram where observation events (search, read, exec) sit on the cool end and mutation events (edit, verify) glow warm, so editing phases stand out. Timeline marks flag context compactions, subagent launches, and user turns as click-to-jump targets. There is a tree view and a treemap terrain view, and mindwalk map <repo> renders any repository's citymap with no session attached, encoding lines of code as height instead of attention.

Usage

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

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

mindwalk serve [--port N] [--claude-dir DIR] [--codex-dir DIR]
mindwalk open <session.jsonl>    # one specific session
mindwalk map <repo>              # a repo map, no session needed
mindwalk build <repo>            # write the citymap JSON
mindwalk trace <session>         # write the normalized trace JSON
mindwalk analyze <session> [--judge claude|codex] [--model name]

Session evaluation is the one feature that sends data off the machine, and only when you explicitly run analyze or click the evaluate panel. It runs your own claude or codex CLI to judge the session's trajectory — exploration, scope, wandering, verification — sending that session's summary (user-message wording, file paths, one-line event digests) to the model behind your account. The judge subprocess runs sealed: no tools, no MCP servers, no user or project settings. Reports cache in ~/.mindwalk/reports, one per session, and go stale rather than auto-rerun when the session changes.

Limitations

• Reads Claude Code and Codex logs only; other agent formats need a new adapter.
• History is per agent session — there is no cumulative view across all your sessions yet (a request raised on the Show HN thread).
• The map is built from the repository as it exists now, so a session against a project you have since deleted renders little on the tree/terrain views even though the timeline still lists the events.
• Session evaluation depends on having a local claude or codex CLI installed and logged in.
• Whether the 3D view earns its keep over git diff is genuinely contested — the HN thread splits between people who find a spatial overview faster on a large repo and people who see added friction for no payoff. It reads best as an evaluation and inspection tool, not a daily driver.

On watchlist: single-author, brand-new, and the value proposition is still being argued out in public. Worth a re-check to see whether it grows cross-session history and picks up adapters beyond Claude Code and Codex.

Related: agentsview analyzes agent sessions as metrics and tables where mindwalk renders them spatially; re_gent captures agent activity as a git-shaped VCS history for audit rather than visualization; the friction signals mindwalk surfaces (error rate, churn, edits after the last verify) are the kind of thing clean-code-coding-agents argues you should be watching for.

Repo: github.com/cosmtrek/mindwalk — 778 stars, MIT license.