Mindwalk: Replay Coding Agent Sessions on a 3D Codebase Map

What Just Happened: Mindwalk in Plain Terms

A developer named cosmtrek shipped an open-source tool called Mindwalk. The core idea is dead simple but surprisingly underexplored: record a coding agent’s entire session—every file read, every edit, every tool call—and replay it as an animation on a 3D map of the actual codebase.

Instead of squinting at a flat terminal log or scrolling through a chat transcript, you see a tiny avatar walking across a top-down, isometric-style file tree. Files light up when the agent touches them. Edits appear as visual pulses. You can scrub backward and forward through time, speed up or slow down playback, and click any file node to inspect its content at that exact moment in the session.

The tool currently supports recording sessions from Claude Code (Anthropic’s CLI coding agent) and Codex CLI (OpenAI’s terminal agent). It captures the full event stream—tool invocations, file modifications, and agent reasoning steps—and serializes them into a JSONL log. A separate replay engine then parses that log, constructs a file-tree graph, and renders it in the browser with Three.js.

That’s what happened. Now let’s talk about why you should care.

Why Spatial Replay Matters for Engineers and FDEs

If you’ve spent any serious time working with coding agents—Cursor, Copilot, Claude Code, Aider—you know the debugging loop is broken. The agent produces a diff. It might be correct. It might be subtly wrong. It might have edited a file you didn’t expect, or read a file you didn’t know existed, or made a decision based on stale context. Your current options for understanding what happened are:

1. Read the chat log. Linear, text-heavy, and terrible at conveying spatial relationships across a codebase.
2. Read the git diff. Shows what changed, not why, not in what order, and not what the agent looked at to get there.
3. Re-run the agent and hope. Expensive, non-deterministic, and doesn’t teach you anything.

Mindwalk addresses a specific cognitive gap: engineers think about codebases spatially. You have a mental map of which modules talk to which, which files are hot, which directories are danger zones. When an agent navigates that space, its path through the tree is information. Did it touch auth.ts before or after database.ts? Did it read config.yaml and then ignore it? Did it loop through the same three files seven times?

These patterns are invisible in a text log but jump out when visualized as motion through space.

For Forward Deployed Engineers (FDEs), this tool hits a particularly sharp nerve. FDEs routinely throw coding agents at unfamiliar customer codebases—sometimes massive, poorly documented monorepos. The agent produces a PR. The customer asks, “Is this safe? Did it understand our architecture?” Without replay, you’re stuck giving a hand-wavy answer. With Mindwalk, you can show them the agent’s exact traversal path, demonstrate that it respected module boundaries, and pinpoint where it sourced its decisions. That’s the difference between “trust me” and “here’s the evidence.”

If you’re building a career in this space, this kind of agent observability is rapidly becoming table stakes. We covered the broader skill set in The Highest-Leverage Skills for an FDE in the AI Era—spatial debugging fits squarely under the “agent evaluation and monitoring” competency that hiring managers are starting to screen for explicitly.

Under the Hood: How Mindwalk Builds the 3D Map

Let’s get concrete about the architecture. Mindwalk has three distinct layers:

1. The Recorder (Session Capture)

Recording is agent-specific. For Claude Code, Mindwalk wraps the agent’s event stream. For Codex CLI, it hooks into the tool-use callbacks. In both cases, the output is a JSONL file where each line is a timestamped event:

{"type": "tool_call", "tool": "read_file", "path": "src/auth/login.ts", "timestamp": 1710800000}
{"type": "tool_result", "tool": "read_file", "path": "src/auth/login.ts", "timestamp": 1710800001}
{"type": "tool_call", "tool": "edit_file", "path": "src/auth/login.ts", "timestamp": 1710800005}
{"type": "reasoning", "content": "The login function uses bcrypt...", "timestamp": 1710800003}

This format is intentionally minimal. It captures what tool was called, which file was affected, and when. The reasoning events are optional but valuable—they let you see what the agent was “thinking” at each step.

2. The Parser (Event Processing)

The replay engine reads the JSONL and builds two data structures:

• A file tree graph representing the actual directory structure of the repo at recording time.
• A timeline of events, indexed by timestamp, with references back to tree nodes.

This separation is clean. The tree is static (it reflects the codebase structure), while the timeline is dynamic (it reflects agent behavior). The renderer layers the timeline onto the tree.

3. The Renderer (Three.js Visualization)

Here’s where it gets fun. The renderer generates an isometric 3D view of the file tree. Each file is a rectangular block. Directories are larger blocks that contain their children. The layout algorithm uses a simple grid-packing approach—not a full force-directed graph, but enough to give you a clear spatial sense.

During replay:

• Files the agent reads pulse with a blue highlight.
• Files the agent edits flash orange or red.
• The agent’s “position” is represented by a small indicator that jumps to the currently active file.
• A scrubber bar at the bottom lets you drag through the timeline.
• Clicking any file node opens a side panel with the file’s content at that timestamp.

Here’s a simplified view of the data flow:

The entire thing runs locally. No telemetry, no cloud dependency. The JSONL log is a plain file you can version-control, share with teammates, or feed into other analysis tools.

How to Run Mindwalk on Your Own Repo Today

You can have this running in under 10 minutes. Here’s the step-by-step:

Prerequisites

• Node.js 18+ (the replay UI is a Vite + React app)
• Claude Code or Codex CLI installed and configured (you need an active API key)
• A codebase you want to analyze (any size, but very large repos may slow the renderer)

Step 1: Clone and Install

git clone https://github.com/cosmtrek/mindwalk.git
cd mindwalk
npm install

Step 2: Record a Session

For Claude Code:

npm run record:claude -- --project-path /path/to/your/repo --prompt "Refactor the authentication module"

For Codex CLI:

npm run record:codex -- --project-path /path/to/your/repo --prompt "Add input validation to the user signup flow"

The recorder will spawn the agent, capture all events, and write a timestamped JSONL file to ./sessions/.

Step 3: Replay

npm run replay -- --session ./sessions/session_2025-03-19T14-22-00.jsonl

This starts a local dev server (usually on localhost:5173). Open it in a browser. You’ll see the 3D codebase map with playback controls.

Step 4: Explore

• Drag the scrubber to jump to any point in the session.
• Click file nodes to see their content at that moment.
• Adjust speed with the playback rate control (0.5x to 4x).
• Toggle event types to show only reads, only edits, or everything.

Pro Tip: Recording for Code Review

Record the agent doing a complex refactor, then share the JSONL file and replay instructions with your reviewer. They can watch the agent’s decision process instead of just staring at the final diff. This is especially powerful for FDE compensation negotiations—being able to demonstrate rigorous agent evaluation practices is a concrete differentiator.

The Balanced Take: Strengths, Gaps, and Where This Fits

Let’s be honest about what Mindwalk is and isn’t.

Strengths

• Zero-config spatial understanding. You don’t need to set up tracing, configure an observability platform, or instrument anything. It just works on any repo.
• Local-first and private. Your code never leaves your machine. The JSONL logs are plaintext, auditable, and git-friendly.
• Agent-agnostic log format. The JSONL schema is simple enough that you could write adapters for Cursor, Aider, or any agent that exposes tool-use events.
• Surprisingly intuitive. Engineers who try it report that patterns they missed in text logs become obvious within 30 seconds of watching the replay.

Gaps and Limitations

• Agent support is narrow. Only Claude Code and Codex CLI today. If you’re a Cursor or Copilot user, you’ll need to wait for community adapters or build your own.
• No semantic understanding. The map shows file-level interactions. It doesn’t show you that the agent read UserModel and then edited AuthService because it understood a dependency between them. That inference is still on you.
• Performance on large repos. The Three.js renderer is not optimized for monorepos with 10,000+ files. Expect frame drops. The maintainer is aware of this and has mentioned potential WebWorker offloading.
• No diff visualization within the 3D view. You can click a file to see its content, but you don’t get a side-by-side diff overlay in the spatial view itself. You’re still cross-referencing between the map and the content panel.
• Single-session only. No comparison mode for “here’s what the agent did on attempt 1 vs attempt 2.” That’s a feature request, not a bug, but worth knowing.

Where This Fits in Your Workflow

Mindwalk is not a replacement for git diffs, CI checks, or code review. It’s a debugging and comprehension tool for the specific moment when you need to understand what a coding agent actually did. Think of it as git log --graph for agent behavior—it doesn’t replace your other tools, but once you have it, you’ll reach for it every time something feels off.

For engineers building agentic workflows—like the YouTube-to-blog repurposing agent or a WhatsApp customer support agent—Mindwalk’s recording format is a pattern worth stealing. The idea of logging every tool call with timestamps and file paths is trivially portable to any agent you build. You don’t need the 3D renderer to get value from structured session logs.

If you’re coming from a backend or frontend background and trying to break into FDE roles, tools like Mindwalk are exactly the kind of thing you should be experimenting with. They signal that you’re thinking about agent evaluation, not just agent usage—and that distinction matters in interviews.

FAQ: Mindwalk for Working Engineers

Q: Does Mindwalk work with Cursor or GitHub Copilot?

Not natively. Mindwalk currently supports Claude Code and Codex CLI because those agents expose clean event hooks. Cursor and Copilot are more closed. Community adapters are possible if those tools expose sufficient APIs, but nothing exists yet.

Q: Can I replay a session without the original codebase?

Partially. The JSONL log contains file paths and event types, so the timeline will replay. But file content inspection requires the actual files at their recorded state. If you’ve changed the codebase since recording, the content panel may show stale or missing data. Best practice: commit the codebase state and the JSONL log together.

Q: How is this different from just reading the agent’s chat transcript?

A chat transcript is linear and text-only. It tells you what the agent said it was doing. Mindwalk shows you what it actually did, in spatial relation to your codebase structure. Patterns like “the agent read 15 files in the utils/ directory but only edited one” are invisible in chat but immediately obvious in the 3D replay.

Q: Is my code sent anywhere during recording or replay?

No. Everything runs locally. The JSONL log stays on your disk. The replay server is localhost-only. There is no telemetry. You can verify this in the source—it’s a small codebase.

Q: Can I use this for compliance or audit trails?

The JSONL format is auditable, timestamped, and git-versionable, which makes it a reasonable lightweight audit log. However, Mindwalk has no cryptographic signing, no tamper detection, and no chain-of-custody features. For high-assurance audit trails, you’d want to layer those on top.

Q: What’s the biggest thing missing right now?

Multi-session comparison. The ability to run the same prompt twice, record both sessions, and visually diff the agent’s paths would be a game-changer for prompt engineering and model evaluation. The maintainer has flagged this as a potential future direction.

Q: Should I use this in production workflows?

For personal debugging and code review? Absolutely. For automated CI gates? Not yet—the tool is early-stage, the agent support is narrow, and there’s no programmatic API for assertions. But the recording format is stable enough that you could build CI tooling around the JSONL logs today if you’re willing to write the integration yourself.