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.
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.
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.
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 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.
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.