Yeah, me too.

Claude Code and Codex both dump massive JSONL session logs. Technically, all the data is there. But parsing 5,000 lines of structured JSON to figure out which files were edited, which were just read, and what the agent actually understood about your project structure? That’s a non-starter. Nobody does it.

So when I stumbled on Mindwalk — a tool that turns those JSONL logs into a 3D, playable visualization of your agent’s session — I had to try it immediately. 317 stars in its first 4 days on GitHub. Honestly? It’s the kind of tool you didn’t know you needed until you see it in action.

TL;DR: What Is Mindwalk?

Mindwalk is an open-source (MIT, Go) visualization tool that reads Claude Code and Codex session logs and replays them on a 3D map of your repository. Think of it as a flight recorder for your AI coding agent — every file the agent read, every file it edited, every context compaction, every subagent launch. All playable like a video.

The core idea: Your agent left a trail. Now Mindwalk lets you actually see it.

How Mindwalk Works: Two Core Concepts

Mindwalk has a clean separation that took me a minute to appreciate. But once it clicked, it made perfect sense.

Trace — The Normalized Event Stream

When you run Claude Code or Codex, it produces a JSONL log of everything that happened. The problem is these logs are raw — full of token dumps, internal state, and noise. Mindwalk’s trace system normalizes all that into a structured event stream: what the agent read, wrote, asked, and when. So it strips the noise and keeps the signal. But what surprised me is how much the trace compression actually reveals — patterns you’d never spot in the raw JSON become obvious in the normalized stream.

Citymap — The Deterministic Repo Layout

Here’s the clever part. Mindwalk builds a deterministic 3D layout of your codebase — call it a “citymap.” Each file becomes a building. The layout is based on your repo’s actual dependency graph and directory structure. Run it twice on the same repo, and you get the same city every time. That consistency is what makes the playback meaningful — you’re not looking at random blobs, you’re looking at your codebase mapped into 3D space.

Then it overlays the trace on the citymap and plays it back. Simple in concept, still surprisingly intuitive in practice.

Three Touch States: What the Colors Mean

Every file your agent interacted with gets color-coded on the 3D map. Mindwalk uses three states:

Within seconds of loading a session, you can see exactly which files got amber highlights. That’s the heatmap of real change. Everything else is noise. Yet that noise is what makes this useful — without the dark areas, you wouldn’t see the focus pattern.

The Playback Deck: Keyboard Controls

Mindwalk includes a full playback UI that runs in your browser (it serves a local React + Three.js frontend). The keyboard shortcuts are straightforward:

Space    — Play / Pause
→        — Step forward one event
E        — Jump to next Edit event
X        — Jump to next Error event

Timeline marks add another layer of readability. The playback bar shows icons for key events:

• ◆ — Context compaction (agent trimmed its context window)
• ○ — Subagent launch (agent spawned a child process)
• › — User turn (you asked something)

So as you watch the playback, you’re not just seeing a blob of light move around. You’re reading the rhythm of how your agent worked. Still, the real power comes from the keyboard shortcuts — stepping through events at your own pace reveals patterns a fast-forward playback would miss.

Quick Start: Getting Mindwalk Running

Installation is a single command, which I always appreciate for Go binaries:

curl -fsSL https://raw.githubusercontent.com/cosmtrek/mindwalk/master/scripts/install.sh | sh

This downloads the binary, verifies it against a checksums.txt, and drops it into ~/.local/bin/. Also add that to your PATH if it isn’t already:

export PATH="$HOME/.local/bin:$PATH"

Then just run:

mindwalk

Mindwalk auto-scans ~/.claude/projects and ~/.codex/sessions for recent logs, picks the latest one, and starts a local server on a random port. Open the URL it prints — usually something like http://127.0.0.1:53721 — and you’re looking at your agent’s session on a 3D map of your repo.

If you want to pick a specific log file:

mindwalk trace --file ~/.claude/projects/my-project/session-20260712.jsonl

Or build a citymap for a specific repo:

mindwalk build --repo /path/to/your/project

That’s it. The whole thing took me about 90 seconds from curl to browser. Now imagine what you can learn when you spend 90 seconds actually watching the playback.

In Practice: What My Session Looked Like

I tested Mindwalk on a session from yesterday when I asked Claude Code to refactor the authentication module in one of my side projects — a FastAPI app with about 15 files in the auth directory.

Here’s what the 3D map showed me in about 3 seconds:

The auth module lit up as a cluster of warm amber buildings right in the center of my repo’s city. A few peripheral files — config, middleware — showed moon white. Still, the rest of the codebase stayed dark moss green or untouched.

So already I could see: the agent stayed focused on auth. Good sign. No rogue file edits in unrelated directories. But then I hit Space to play the timeline, and the real story emerged.

The trace showed the agent started by reading three key files (moon white blinking), then made a series of edits (amber pulses) to the main auth handler. About halfway through, there was a ◆ mark — context compaction. The agent had trimmed its window. Right after that, it edited a file I didn’t expect: middleware.py. Not a problem, but I hadn’t explicitly asked for middleware changes. Though honestly, that’s exactly the kind of surprise this tool is designed to surface.

Without Mindwalk, I would never have caught that. I’d have submitted the PR, reviewed the diff, and completely missed the collateral edit. That kind of blind spot is exactly why agent observability matters.

Then there was an ○ — subagent launch. Claude Code had forked a child agent to handle the JWT token validation refactor in parallel. Now watching the city split into two simultaneous light trails — one in the auth handler, one in the token utils — was genuinely impressive.

How Mindwalk Compares: The Alternatives

The honest take: If you only run short, single-file Claude Code sessions, you probably don’t need Mindwalk. You can read the diff. But if you’re doing multi-file refactors, full-codebase migrations, or anything where your agent runs for 50+ turns — this tool saves you real time. Brain0 answers “WHY did my agent make this decision.” Mindwalk answers “WHAT did my agent actually touch.” Still, they’re complementary. Now here’s the thing — having both gives you a complete observability picture.

For a deeper look at building production-ready applications with LLMs and orchestrated agents, Building LLM Powered Applications covers prompt chaining, multi-agent coordination, and observability patterns — the engineering side of exactly what these tools help you monitor (affiliate link).

Things to Watch Out For

I ran into a few rough edges worth mentioning:

Early project volatility. Mindwalk has 317 stars and a 4-day GitHub history. It’s MIT-licensed and actively maintained, but the API could shift. The CLI flags might change. The trace format could evolve with new Claude Code releases. So if you’re building a workflow around it, pin the binary version. Even better, check the release page before every major upgrade.

Large repos can be slow to build. The citymap generation runs a dependency analysis on your repo. For my small side project (~200 files), it took about 4 seconds. For a monorepo with 10,000+ files, expect a noticeably longer wait. The README mentions this is a known optimization target.

Claude Code / Codex only. Mindwalk currently supports Claude Code and Codex session logs. But if you’re using Cursor, Windsurf, or Aider — those formats aren’t supported yet. The project says more formats are planned, though there’s no ETA.

Don’t mistake visualization for audit. Mindwalk is a visualization tool. It helps you see what your agent did. It doesn’t automatically flag security issues, detect logic errors, or validate your tests. So use it to understand your agent’s behavior faster — then still read the diff.

Who Should Use Mindwalk

• Claude Code power users doing complex, multi-file refactors
• Team leads reviewing AI-generated PRs — share the citymap visualization with your team
• Agent workflow builders debugging why their agent keeps touching the wrong files
• Security-conscious teams running agents in isolated sandboxes — pair Mindwalk’s visibility with E2B’s microVM environments
• Anyone who’s ever thought “I wish I could just see what Claude Code did”

Who can skip it: casual users running one-shot codegen queries. Because if your sessions are 3-4 turns and touch one file, the diff is faster. But for everyone else — especially if you’ve ever approved a PR and regretted it — Mindwalk is worth the 90-second setup.

The Bottom Line

Mindwalk is one of those rare tools that makes you feel like you’ve been working blind without it. It’s not solving a hypothetical problem — every Claude Code user has wondered what their agent actually did. 317 stars in 4 days tells me I’m not the only one who felt the pain.

My verdict: Install it. Run it on your last Claude Code session. The 90-second install cost is worth the one “oh wait, it edited that?” moment you’ll have within the first 30 seconds of playback.

While Brain0 answers why your AI agent made its choices, Mindwalk shows you what it actually touched. Between the two, you get a complete picture of your agent’s behavior. That’s the direction agent observability is heading — and I’m here for it. Though I’ll say this: even without Brain0, Mindwalk alone already changes how you think about agent transparency.

Curious about the other half of the picture? Mindwalk and a code-provenance audit tool together give you a complete view of agent behavior.

Still using Claude Code without any session visibility? Try Mindwalk this afternoon. You’ll be surprised what you find.

Recommended reading: Building LLM Powered Applications — a hands-on guide to building, testing, and deploying LLM agents in production. Covers the patterns this article touches on at the code level.