What happened. Mindwalk is a local visualizer that reads session logs from Claude Code and Codex and replays them on a 3D repository map: each file becomes a point in space, and the agent’s activity (search, read, modify) lights up that zone on the map. A downloadable Go binary, entirely local, no data leaves your machine. The project is on GitHub under MIT license.

Why it matters to you. When you delegate a task to a coding agent, the JSONL log tells you what it did, not how it understood the problem: which parts of the repo it explored, where it focused, whether its path matched what you had in mind. Mindwalk transforms that sequence into a form you can see at a glance: the agent’s understanding of the task becomes a heat map across your codebase. If the agent touched files that are irrelevant, or skipped the central ones, you see it immediately. It’s useful for debugging agents that fail (where did it get lost?) and for improving prompts (did I give it enough context about the structure?).

To try it. The repo contains an installation script that verifies the signature and installs the binary to ~/.local/bin. Once installed, mindwalk with no arguments reads the Claude Code and Codex folders and opens the web interface locally. The UI features a histogram timeline (observation vs mutation actions), play/pause and scrub controls, and an inspector showing each file’s visit history when clicked.

In detail

The context

Coding agents — Claude Code, Codex, Cursor in agent mode — produce detailed logs of every action (files opened, searches, edits, executions). But reading a JSONL line by line doesn’t answer the most important question: did the agent understand the problem the way you imagined it? Did it explore the right parts of the repo, or focus on areas that don’t matter?

Mindwalk starts with the idea that an agent’s understanding of a task has a spatial shape: it can be represented as a map of light and shadow across your codebase. Where the agent searched, read, and modified, the map lights up; everything else stays dark.

How it works

The tool has two main modes:

• Serve mode (mindwalk with no arguments): scans Claude Code folders (~/.claude/projects) and Codex (~/.codex/sessions), generates maps of the involved repositories, launches a local server on a random port, and opens your browser. From there you can pick a session from the list and watch its replay.
• Open mode (mindwalk open <session.jsonl>): opens a specific session without scanning everything.

The visual representation offers two views: Tree (radial tree of folder structure) and Terrain (flat treemap, each file is a rectangle sized by visit count). Each file carries a touch state that evolves with the session: seen (moss green, file encountered in a search), read (lunar white, file opened), edited (warm amber, file modified), unvisited (dark). The state tracks the deepest level reached.

The timeline histogram below the map shows session activity in time buckets across a cold/warm spectrum: observation actions (search, read, exec) stay cool, mutations (edit, verify) warm up. Editing phases pop out visually. The timeline shows clickable markers: context compactions (◇), subagent launches (○), user turns (›).

The HUD at the top summarizes friction signals: error rate, files edited multiple times (churn), edits after the last verification. The inspector on the side opens when you click a file and shows its visit history with timestamps; each row jumps the playhead to that moment.

The limits

Mindwalk works only on logs that tools produce. If an agent holds internal conversations or reasoning that doesn’t end up in the structured log, those stay invisible. The map shows where the agent went, not why: to reconstruct the reasoning you still need to reread the session messages.

The tool currently supports only Claude Code and Codex. Other coding agents (Cursor, Windsurf, Zed AI) produce logs in different formats: each will need a parser, or a shared standard (none exists yet).

Finally, 3D visualization is useful for medium-small repositories. On massive monorepos (thousands of files) the map becomes hard to navigate: the tool doesn’t yet scale well beyond a certain threshold.

What to do with it

Mindwalk doesn’t tell you if the agent did good work: it tells you if it understood the problem like you did. If a refactoring task touched only half the files you knew were involved, you’ve found a problem in the brief or the context passed. If the agent modified config files that don’t matter, you’ve found a tool called at the wrong time or an ambiguous prompt.

It’s a tool for debugging the prompt, not the code produced. After seeing the map, you go back to the agent’s brief and rewrite it with the missing context, or better define tool boundaries.

For those building custom agents or running multi-agent orchestration experiments, Mindwalk can become part of the development cycle: run the task, watch the map, fix, rerun. It’s the same loop you do with a performance profiler, but applied to task understanding instead of execution time.