Mindwalk - Session Replay Visualization for Codebases
Replays coding-agent sessions on a 3D map of your codebase, revealing how the agent understood the task at a glance.
- Source repo
- cosmtrek/mindwalk
- Stars
- ★ 1.4k
- Last updated
- 2mo ago
- License
- MIT
- Primary language
- Go
- FA score
- 59/100 · Major gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformChatGPT · Codex · Claude Code
- Cost
- Free software; you pay for model usage
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- A developer wants to assess how a coding agent explored a large repository before making edits, checking if its footprint matches the intended scope. Mindwalk's visualization makes the agent's understanding visible at a glance.
- Not a fit if
- Teams using agents other than Claude Code, Codex, or pi
- Teams unwilling to send session summaries to a model API
- Source review
- 59/100 · Major gaps
What does this agent do, and when should you use it?
Mindwalk is a visualization tool that replays coding-agent sessions on a 3D map of your codebase, turning raw session logs into an interactive visual story. It reads log files from Claude Code, Codex, and pi (all processed locally), and renders the repository as a 'night map' where file touch intensity (glow) represents how deeply and often each file was accessed. The tool offers tree and terrain views, playback controls with speed adjustment and video export, timeline marks for context compactions, subagent launches, and user turns, plus subagent lenses to replay individual subagent traces. It also includes an optional session evaluation feature that calls your local claude or codex CLI to judge the session against fixed process dimensions and a dynamic task scorecard, with reports cached locally. All processing is fully local, and the only exception is when evaluation is explicitly invoked. The project consists of a Go server and a React/Three.js frontend.
Mindwalk normalizes session logs (e.g., JSONL files from ~/.claude/projects) via adapters in internal/adapter, producing an ordered stream of file-touch events (the trace) and correlating subagent sessions into an agent graph. It generates a deterministic 3D layout of the repository (the citymap) via internal/citymap, encoding touch depth and frequency as glow. Users launch the tool with mindwalk (scans default directories and opens a browser) or mindwalk serve for a custom port, open a specific session with mindwalk open <session.jsonl>, or render a repository map with mindwalk map <repo>. The CLI also offers mindwalk build and mindwalk trace to export citymap and trace JSON. The UI supports playback controls, timeline scrubbing, subagent lenses, file click-to-inspect, and .webm export. The evaluation feature (mindwalk analyze or the UI panel) calls the local claude or codex CLI to draft criteria and score the session, producing a report cached in ~/.mindwalk/reports.
- A developer wants to assess how a coding agent explored a large repository before making edits, checking if its footprint matches the intended scope. Mindwalk's visualization makes the agent's understanding visible at a glance.
- A team reviewing an agent's code changes needs to see where the agent searched, read, and edited, to catch wasted effort or missed critical files.
- When an agent behaves unexpectedly, a user can replay the trace of a subagent independently via agent lenses to diagnose the reasoning path.
- A tech lead compares multiple sessions using the evaluation feature, which scores them on consistent dimensions (exploration, scope, wandering, verification) and task-specific criteria.
- A user wants to explore an unfamiliar repository's structure without any session:
mindwalk map <repo>renders a 3D citymap where height indicates lines of code.
How do you install or deploy this agent?
Install via the official script: run curl -fsSL https://raw.githubusercontent.com/cosmtrek/mindwalk/master/scripts/install.sh | sh, then add ~/.local/bin to your PATH (export PATH="$HOME/.local/bin:$PATH") and run mindwalk. The installer verifies checksums and installs to ~/.local/bin (override with INSTALL_DIR, pin a release with VERSION). Windows users can download archives from GitHub Releases. Building from source requires Go and Node.js: run make setup && make build.
How do you use this agent?
Simply run mindwalk with no arguments to scan default session directories (~/.claude/projects, ~/.codex/sessions, ~/.pi/agent/sessions), start a random local port, and open the browser. For more control, use mindwalk serve --port N --no-open to set a port, mindwalk open <session.jsonl> to open a specific session, mindwalk map <repo> to open a repository map, mindwalk build <repo> [-o out] to write a citymap JSON, and mindwalk trace <session> [-o out] to write a normalized trace JSON. To evaluate a session, run mindwalk analyze <session> [--judge claude|codex] [--model name] [--no-rubric]. In the UI, use Space for play/pause, arrow keys to step, S speed, V view, E next edit, X next error, M next mark, and ⌘B to toggle the session rail.
What are this agent's strengths and limitations?
- Fully local processing: session data never leaves your machine unless you explicitly trigger evaluation, and even then only a summary is sent to your own CLI's model, ensuring privacy.
- Intuitive and unique visualization: the 3D night map with glow intensity and touch states makes agent behavior much easier to grasp than reading raw JSONL.
- Multi-agent support: natively reads logs from Claude Code, Codex, and pi, and allows replaying subagent traces individually.
- Deterministic citymap generation: the same repository always yields the same map, enabling fair comparisons across sessions.
- Limited to supported agent formats: requires adapters for other agents, which are not included out of the box.
- Installation footprint: requires Go and Node.js environments and a network download; may not suit fully offline setups.
- Evaluation depends on external CLIs: you must have
claudeorcodexinstalled, and evaluation calls may incur API costs. - Learning curve: the feature-rich UI and CLI may take time to master for new users.
How does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Mindwalk - Session Replay Visualization for Codebases This agent | 59 · Major gaps | CLIFree + model costs | ★ 1.4k | 2mo ago | Go | ChatGPT · Codex · Claude Code |
| Paseo | 49 · Major gaps | Desktop appFree + model costs | ★ 21k | today | TypeScript | ChatGPT · Codex · Claude Code · OpenAI API |
| OpenCove Infinite Canvas Workspace | 46 · Major gaps | Desktop appFree | ★ 1.6k | 2d ago | TypeScript | Codex · Claude Code |
| img2threejs — Code-Only 3D Reconstruction | 45 · Major gaps | Agent plugin / skillFree + model costs | ★ 18k | 11d ago | Python | Codex · Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows: tool runs locally by default, only sends session summary to local CLI when user explicitly runs evaluation; installer verifies checksums; no network requests. Deductions: only one dependency (jsonschema) but no vulnerability scanning or lockfile details; rollback mechanism not specified; publisher identity unverified.
Evidence shows: README description consistent with code structure, CI tests and frontend build verification; dependencies are Go standard library and few third-party, high availability. Deductions: failure messages not detailed in docs, error handling details not shown.
Evidence shows: targets developers, supports multiple agent formats and platforms (Linux, macOS, Windows, Nix); capability boundaries clear (read-only session logs, evaluation requires explicit invocation); trigger conditions clear (command-line arguments). Deductions: environment adaptation details (e.g., specific shells, permissions) not fully specified.
Evidence shows: README structure clear, installation instructions detailed, naming stable (commands and arguments consistent), examples and FAQ present (via docs and screenshots), MIT license explicit. Deductions: known limitations not explicitly listed, version changelog not provided, maintenance responsibility unclear (publisher unverified).
Evidence shows: output is visual interface and JSON files, directly usable; marginal value high (solves session understanding problem); low cost (local, free). Deductions: no cost-benefit analysis, but overall reasonable.
Evidence shows: README claims consistent with code structure, tests and CI present; docs distinguish facts and inferences (e.g., evaluation reports). Deductions: cross-source corroboration insufficient (only single repository evidence).
- Publisher identity unverified; installer fetches from remote, verify checksums.
- Evaluation feature sends session summary to local CLI; ensure understanding of data flow.
- Few dependencies, but no vulnerability scanning; recommend regular checks.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
Changelog * 68aeda671a48eb6e406792e984d3570f28dc5e70 Tip for Nix users (#24) * a3569baa875d8c5f8fde2e7c93896f99af39c029 server: component boundaries — traceStore, adapter sidecar interface, report index, loopback hardening (#23) * 9a262e25d9024c8433fc670d6e7491c7bedf5b12 feat(citymap): bounded adaptive scanning for oversized session roots (#22)View on GitHub ↗ -
Release notes excerpt
Changelog * b3b98a033ebc5eddc286efe4549b08d87d95aba9 feat(adapter): support pi sessions (#20) * e49e9e672dfe29c570b5b44d3f523f4ca0760083 fix: update star history chart links in README * 7721e6e964676b8b2204e2e8d8fd67d318969833 feat: task-rubric layer for session evaluation (#19) * e208b6b8504138843f671e031f28129b66003a67 docs: update demo video made by kimi k3 * 3f614a90a7a77c3ab14ba7f2c4c7bbd057b762d5 chore: remove obsolete demo video ignoreView on GitHub ↗ -
Release notes excerpt
Changelog * b9c12798d012f8600d015a429a1ed7f9cdef4f69 docs: fix asset URL in README.md * 81b408abc48566e26f2e58aa7f8d3dc9a65fa72f docs: update demo link * e0ae880b84c517e111b58470f6585f5a22b0c61a docs: refresh README screenshots and feature notes * 823e862499416cf5c6e97523a18868220590ee3f fix(adapter): show nested Codex exec summaries * 05081bcb4ac9bb7afb89f756d2721988f9c4ebaa feat: add Agent Lens for subagent traces (#12) * 8a28839f5b0dd6bc64401af226508068a70037ae fix: centralize UTF-8-safe truncation * 6e8c7883f1df6fb312ad8872c435672037b795df fix: preserve UTF-8 in judge errors (#13) …View on GitHub ↗
FAQ
Can Mindwalk analyze sessions from agents other than Claude Code, Codex, or pi?
What does the evaluation feature send externally?
claude or codex CLI, up to two sealed calls. Nothing else is sent, and viewing sessions never sends data.