This project provides a visualization tool for replaying coding-agent sessions, transforming raw logs into an intuitive 3D map of a codebase. It addresses the challenge of understanding an agent's cognitive process—its perceived relevance, exploration patterns, and scope—which is lost in standard log formats. The tool offers a clear, visual representation of agent activity, benefiting developers and researchers seeking to analyze or debug AI-assisted coding workflows.

How It Works

A single, local Go binary processes session logs from agents like Claude Code and Codex. It generates two core artifacts: a trace representing normalized file-touch events and a citymap defining a deterministic layout of the repository. A local Go server then serves a React/Three.js frontend that visualizes the trace overlaid onto the citymap. This approach ensures data privacy by keeping all processing local and provides a novel, spatial metaphor for understanding agent behavior, making exploration and editing phases immediately apparent.

Quick Start & Requirements

• Install: Execute curl -fsSL https://raw.githubusercontent.com/cosmtrek/mindwalk/master/scripts/install.sh | sh and ensure ~/.local/bin is in your PATH.
• Prerequisites: Standard shell environment for installation script.
• Build from Source: Run make setup && make build.
• Usage: mindwalk serve (scans ~/.claude/projects and ~/.codex/sessions by default), mindwalk open <session.jsonl>, mindwalk build <repo>, mindwalk trace <session>.

Highlighted Details

• Visualization: Renders the repository as a radial tree or treemap, with file "glow" intensity indicating touch depth and frequency.
• Touch States: Files are color-coded: seen (moss green), read (moon white), edited (warm amber), or unvisited (dark).
• Playback Deck: Scrub or play sessions over a histogram, with cool colors for observation (search, read) and warm colors for mutation (edit, verify).
• Timeline Marks: Clickable markers for context compactions (◇), subagent launches (○), and user turns (›) allow direct navigation.
• Inspector: Pin file visit histories and jump the playhead to specific moments.
• Friction Signals: A HUD displays error rates, churned files, and edits after the last verify.

Maintenance & Community

Issues and pull requests are welcomed. Development setup includes make setup for frontend dependencies and make serve for a local development server. Comprehensive architectural notes are available in AGENTS.md.

Licensing & Compatibility

The project is licensed under the MIT license. This permissive license allows for commercial use and integration with closed-source projects without significant restrictions.

Limitations & Caveats

The tool currently focuses on processing logs from specific agents (Claude Code, Codex). No explicit limitations regarding platform support, alpha status, or known bugs are detailed in the provided documentation.