mindwalk: replay a coding-agent session on a 3D map of your repository

The question a session log refuses to answer

A session log is a list of things that happened. It records that a file was read, a command was executed, an edit was applied. What it does not record is how the agent understood the task: which parts of the repository it treated as relevant, where it wandered before it acted, and whether the ground it covered matches the scope you had in mind. The README puts the problem plainly, saying that reading the raw JSONL line by line does not answer any of that.

That gap matters most after the fact. You have a diff, you have a transcript, and you still cannot tell whether the agent spent forty events exploring a module it never touched, or whether it edited a file it had never read. mindwalk is built for the person who has to make that judgement: a reviewer, a maintainer, or the engineer who wrote the prompt and wants to know how much of the repository the agent actually considered. It is not a debugging tool for the agent's code, and it is not a dashboard for token spend.

How a session becomes light on a night map

The design rests on three artifacts that the README describes as deliberately separate. The first is a trace: the session log normalized into an ordered stream of file-touch events, produced by the adapters under internal/adapt. The second is a citymap, the repository rendered as a map. The third is the playback that plays one against the other.

On screen, the repository appears as a radial tree or a treemap plain. Each file keeps its deepest touch state, and the states are named in the README: seen is moss green, read is moonlight blue, edited is warm amber, and unvisited stays dark. Glow scales with how deeply and how often a file was touched. Files that the session touched but that no longer exist in the repository linger as wireframe ghosts, which is a small detail that quietly handles the common case of an agent working across a refactor.

The playback deck scrubs or plays the session over a bucketed histogram of the run. Bars sit on a cool to warm spectrum, with observation (search, read, exec) staying cool and mutation (edit, verify) glowing warm, so editing phases stand out without reading any numbers. Timeline marks flag context compactions, subagent launches and user turns, and each mark is a click target. Where a session launched subagents, an agents panel lets you replay any single subagent's trace on the same map and step back out to the main trace. Clicking a file pins its visit history, and clicking a visit row moves the playhead to that moment.

Installing mindwalk and opening your first session

The README gives a one-line installer that downloads the binary, verifies it against checksums.txt and places it in ~/.local/bin. INSTALL_DIR overrides the destination and VERSION pins a release.

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

With no arguments, mindwalk scans ~/.claude/projects, ~/.codex/sessions and ~/.pi/agent/sessions, serves the UI on a random local port and opens a browser. If your logs live elsewhere, the serve command takes directory flags for each source.

mindwalk serve [--port N] [--no-open] [--claude-dir DIR] [--codex-dir DIR] [--pi-dir DIR]

To look at a single session rather than the whole scan, pass the file to open. To see a repository with no session attached, use map, where height encodes lines of code instead of attention.

mindwalk open [--no-open] <session.jsonl>
mindwalk map [--no-open] <repo>

Two subcommands write the intermediate artifacts to disk instead of opening a browser: build writes the repository citymap JSON and trace writes the normalized trace JSON, each with -o for the output path.

mindwalk build <repo> [-o out]
mindwalk trace <session> [-o out]

Building from source is a Go and Node affair: make setup runs npm ci in web, and make build produces bin/mindwalk. The Makefile also has a serve target that runs the binary on port 8765 with --dev. Windows archives are on GitHub Releases, and Nix users can pull mindwalk from the numtide/llm-agents flake.

Session evaluation, and the one thing that leaves your machine

Viewing is local. The README states that the single exception is session evaluation, and it is worth reading that section twice before switching it on. When you run it, mindwalk shells out to your own claude or codex CLI for up to two sealed calls: one drafts criteria from your request wording, one scores the session. Both send a summary of that session only: the user messages' wording, file paths, and one-line event digests. Nothing is sent while you are viewing sessions, and no other session is included. The judge subprocess runs with no tools, no MCP servers, no user or project settings and no session persistence.

The report has two layers. Process dimensions are four fixed lenses (exploration, scope, wandering, verification) that stay the same across sessions so reports remain comparable. The task scorecard is drafted per session from your own request, grouped per task when a session carried several, and each criterion is scored in the same pass as the dimensions. Two design choices are worth crediting. Every finding must cite timeline events you can click through to, and no verdict is left to the model: dimension and criterion verdicts are rolled up mechanically from finding severities. When the log cannot show whether a criterion was met, coverage drops and the verdict reads "no signal", which the README frames as a blind spot rather than a failure.

The failure modes are documented rather than hidden. Sessions with no tool events or too little task text skip the scorecard, and a failed criteria draft degrades to a dimensions-only report. Passing --no-rubric, or setting "rubric": false on the analyze API, skips it explicitly in a single judge call. Reports are cached in ~/.mindwalk/reports, one per session, and go stale when the session's content changes without ever re-running on their own. Re-evaluating a session whose task wording is unchanged reuses the drafted criteria, so scores can move while the yardstick stays fixed.

Where mindwalk is the wrong tool

The adapter list is the hard boundary. mindwalk reads Claude Code, Codex and pi session logs, and the default scan looks in three specific directories. If your agent writes its transcript in another format, or your team pipes logs into a hosted observability service and keeps nothing on disk, the trace stage has nothing to normalize and the map stays dark. There is a schema/ directory and a documented trace format, so an adapter is a conceivable extension, but the repository does not present a plugin interface for it.

The second limitation is the evaluation layer's dependence on a local agent CLI. The judge is your installed claude or codex, which means the feature is unavailable in an environment where those CLIs are absent or where outbound model calls are blocked. That is a deliberate trade: the README is explicit that the evaluation sends a session summary to the model behind your own account. If a session contains something that may not leave the machine, the honest answer is to use mindwalk for viewing and leave the evaluate panel alone.

Third, the visualisation answers a question about shape, not correctness. A clean glowing map of a well-scoped session says nothing about whether the resulting code is right, and a scattered map of a messy session can still end in a correct patch. Treat the picture as a prompt for a review conversation, not as a verdict on the change.

mindwalk against a plain session viewer

The closest everyday alternative is not another visualisation tool but the transcript viewer you already have: the JSONL file itself, or whatever the agent CLI prints when you re-open a session. That approach wins on fidelity and setup cost. Every event is there, in order, with no normalisation step in between, and it works for any agent that writes a readable log.

What it cannot do is compress the session into a shape. Scrolling a transcript tells you what happened next; it does not tell you that an agent read eleven files in one package and then edited a twelfth it had never opened, because those two facts may sit hundreds of lines apart. mindwalk's contribution is the projection onto the repository map, where depth of touch becomes brightness and the untouched remainder stays visibly dark. The trade is real: you lose the raw event text in the default view and have to click into the inspector for visit history, and you pay for the projection with an adapter that only understands three log formats. If you mainly want to search a transcript for a specific command, the raw file is still the faster tool.

Maintenance, licence and what an upgrade costs you

The repository is not archived, and the last push was on 2026-08-10, with v0.5.0 released on 2026-08-07, v0.4.0 on 2026-08-03 and v0.3.0 on 2026-07-18. That is a short release cadence across three minor versions in under a month, which is worth knowing before you build anything on top of the on-disk artifacts. The trace and citymap JSON formats are the surface most likely to move, since the README describes them as separate artifacts and the schema/ directory exists to pin them; if you script against mindwalk trace or mindwalk build output, check the schema after an upgrade rather than assuming the shape held.

The project is MIT licensed, so redistribution and modification are permitted under the usual terms; that is a statement about the licence text, not legal advice, and anyone embedding mindwalk in a product should read the LICENSE file in the repository. One licence-adjacent detail the README does flag: the optional evaluation sends data to the model behind your own claude or codex account, so the terms that govern that call are your provider's, not the MIT grant.

The upgrade path is otherwise cheap. The install script verifies the downloaded binary against checksums.txt, and VERSION pins a specific release if you would rather not track the latest. Reports cached in ~/.mindwalk/reports are keyed per session and go stale when a session's content changes, so an upgrade does not silently rewrite old evaluations.

Editorial conclusion

Adopt mindwalk if you already keep Claude Code, Codex or pi session logs and want to see the shape of an agent's attention before you review its diff. Skip it if your agent writes logs somewhere else, or if nothing in the session may leave your machine, because the evaluate panel and mindwalk analyze send a session summary to the model behind your own claude or codex CLI. Verify three things first: that the session files are where the default scan looks, that the exported trace JSON carries the file paths your review depends on, and that your Go toolchain and Node setup can run make setup && make build if you would rather not pipe the install script to sh.

Frequently asked questions

Official sources

1. cosmtrek/mindwalk on GitHub
2. Issues
3. License: MIT
4. README
5. Releases