mindwalk

What it is

A visualization tool that replays coding-agent sessions on a 3D map of your codebase.

How it works

A local Go server joins trace, citymap, and report artifacts to serve a React/Three.js frontend. The tool supports an optional session evaluation flow by invoking a local agent CLI (claude or codex) to judge a session. The repository provides three artifacts: a trace (normalized session log), a citymap (deterministic layout), and a report (LLM judge findings). The evaluation data leaves your machine only when you run it and explicitly request evaluation.

Getting started

"curl -fsSL https://raw.githubusercontent.com/cosmtrek/mindwalk/master/scripts/install.sh | sh" "export PATH="$HOME/.local/bin:$PATH"" "mindwalk"

The installer verifies the binary against checksums.txt and installs to ~/.local/bin (override with INSTALL_DIR; pin a release with VERSION). Windows archives are on GitHub Releases. To build from source: make setup && make build → bin/mindwalk.

With no arguments, mindwalk scans ~/.claude/projects and ~/.codex/sessions, serves the UI on a random local port, and opens a browser:

mindwalk serve [--port N] [--no-open] [--claude-dir DIR] [--codex-dir DIR]
mindwalk open [--no-open] <session.jsonl>   open one specific session
mindwalk map [--no-open] <repo>             open a repository map, no session needed
mindwalk build <repo> [-o out]              write the repository citymap JSON
mindwalk trace <session> [-o out]           write the normalized trace JSON
mindwalk analyze <session> [--judge claude|codex] [--model name]
                                            evaluate one session (see below)

Reading the picture

• Tree/Terrain views show repo structure with glow indicating file touches.
• Touch states indicate seen/read/edited/unvisited with color cues.
• Playback deck supports scrub/play, speed, and video export stored client-side.
• Timeline marks and agent lenses aid navigation through session events.
• Repo map renders the citymap for a repo without a session; height encodes lines of code.
• The Session evaluation path uses a local agent CLI to judge the session; evaluation results attach to session UI entries and are cached in ~/.mindwalk/reports.

Session evaluation

The evaluation panel and mindwalk analyze invoke a local agent CLI to judge exploration, scope, wandering, and verification, anchored to timeline events. The evaluation process is explicit: the judge (any installed CLI) and its model are chosen in the panel; the report records who judged. The leaves-your-machine behavior is limited to the evaluation run.

Under the hood

Three artifacts are produced and kept separate:

1. a trace (normalized session log)
2. a citymap (deterministic layout)
3. a report (judge findings) A local Go server (internal/server) serves the React/Three.js frontend (web). schema/ mirrors the exported JSON contracts.

Contributing

To get a working dev setup:

make setup   # install frontend dependencies
make serve   # dev server on :8765, serving web/dist from the working tree
make test    # go test + frontend build — run before sending a PR
make build   # regenerate embedded assets and bin/mindwalk