# mindwalk

> A visualization tool that replays coding-agent sessions on a 3D map of your codebase, showing where the agent searched, read, and edited files.

mindwalk is an open-source CLI tool built in Go that turns raw coding-agent session logs into an interactive 3D visualization of your repository. Created by Ricko Yu and released under the MIT license, it reads Claude Code and Codex session logs locally — no data leaves your machine during viewing — and renders the agent's activity as light moving through a night-map of your codebase.

## What It Is

mindwalk sits in the category of developer observability and agent-session analysis tools. Its core job is to answer a question that raw JSONL logs cannot: not just *what* a coding agent did, but *how* it understood the task — which parts of the repo it treated as relevant, where it explored before acting, and whether its footprint matched the intended scope. The tool produces a local web UI backed by a Go server serving a React/Three.js frontend, all packaged as a single binary.

## How the Visualization Works

The repository is drawn as a "night map" and the session plays back as light moving through it. Three visual modes and several interactive layers make the session readable at a glance:

- **Tree / Terrain views** — the repo rendered as a radial tree or a treemap plain; glow intensity reflects how deeply and how often a file was touched.
- **Touch states** — each file holds its deepest touch: seen (moss green), read (moon white), edited (warm amber), unvisited (dark).
- **Playback deck** — a bucketed histogram of the run on a cool/warm spectrum; observation events (search, read, exec) stay cool, mutation events (edit, verify) glow warm.
- **Timeline marks** — context compactions (`◇`), subagent launches (`○`), and user turns (`›`) are all click-to-jump targets.
- **Inspector** — click any file to pin its visit history and jump the playhead to any moment.

Keyboard shortcuts cover play/pause, stepping, speed, and jumping to the next edit, error, or mark.

## Architecture: Three Deliberate Artifacts

The README describes three artifacts kept intentionally separate to ensure replays are comparable across sessions:

1. **Trace** — the session log normalized into an ordered stream of file-touch events, with one adapter per agent format (`internal/adapter`).
2. **Citymap** — a deterministic layout of the repository (`internal/citymap`); the same tree always produces the same map.
3. **Report** — an LLM judge's evidence-anchored findings about one session (`internal/judge`); verdicts are rolled up mechanically so reports stay comparable.

A local Go server joins these artifacts and serves the React/Three.js frontend. JSON contracts are mirrored in `schema/`.

## Session Evaluation and Privacy Model

An optional evaluate panel (also accessible via `mindwalk analyze`) asks a locally installed agent CLI — Claude Code or Codex — to judge the session's trajectory across dimensions like exploration, scope, wandering, and verification. Every finding is anchored to timeline events that are clickable in the UI. The privacy boundary is explicit: evaluation sends only the session's user-message wording, file paths, and one-line event digests to the model behind the user's own CLI account. Nothing is sent during passive viewing. The judge subprocess runs sealed with no tools, no MCP servers, and no session persistence. Reports are cached in `~/.mindwalk/reports` and go stale only when session content changes.

## Update: v0.1.0

The first release, v0.1.0, was published on July 11, 2026, roughly two days after the repository was created on July 9, 2026. The project accumulated 580 stars and 33 forks within about a week of creation, signaling strong early interest from the developer community. Installation is via a shell script that verifies the binary against `checksums.txt` and places it in `~/.local/bin`; Windows archives are available on GitHub Releases. Building from source requires `make setup && make build`.

## Features
- 3D visualization of coding-agent sessions on a repository map
- Supports Claude Code and Codex session log formats (JSONL)
- Tree and Terrain views (radial tree and treemap)
- Touch state color coding: seen, read, edited, unvisited
- Playback deck with cool/warm histogram spectrum
- Timeline marks for context compactions, subagent launches, and user turns
- File inspector with visit history and playhead jump
- Optional session evaluation via local agent CLI (Claude or Codex)
- Fully local viewing — no data sent during session replay
- Deterministic citymap layout for comparable cross-session replays
- Keyboard shortcuts for playback control
- Single Go binary with shell-script installer
- Cached evaluation reports in ~/.mindwalk/reports
- CLI commands: serve, open, build, trace, analyze

## Integrations
Claude Code, OpenAI Codex, React, Three.js

## Platforms
WINDOWS, WEB, API, CLI

## Pricing
Open Source

## Version
v0.1.0

## Links
- Website: https://github.com/cosmtrek/mindwalk
- Documentation: https://github.com/cosmtrek/mindwalk
- Repository: https://github.com/cosmtrek/mindwalk
- EveryDev.ai: https://www.everydev.ai/tools/mindwalk