Mindwalk: Claude Code & Codex 세션의 3D 재생 도구

Mindwalk는 코드베이스의 3D 맵에서 코딩 에이전트 세션을 재생하는 시각화 도구입니다. 원시 JSONL 세션 로그를 들여다보는 대신, 에이전트가 검색, 읽기, 편집할 때 빛이 이동하는 야간 지도를 볼 수 있으며, 손대지 않은 부분은 어둡게 유지됩니다.

해결하는 문제

세션 로그는 에이전트가 무엇을 했는지는 알려주지만, 작업을 어떻게 이해했는지—리포지토리 중 어떤 부분을 관련 있다고 판단했는지, 행동하기 전에 어디를 탐색했는지, 그 발자국이 사용자의 의도와 일치했는지는 알려주지 않습니다. JSONL을 한 줄씩 읽어서는 답을 얻을 수 없습니다.

빠른 시작

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

설치 프로그램은 checksums.txt에 대해 바이너리를 검증하고 ~/.local/bin에 설치합니다(INSTALL_DIR로 재정의 가능, VERSION으로 특정 릴리스 고정). Windows 아카이브는 GitHub Releases에 있습니다. 소스에서 빌드하려면: make setup && make build → bin/mindwalk.

명령어

인수 없이 실행하면 mindwalk는 ~/.claude/projects와 ~/.codex/sessions를 스캔하고, UI를 임의의 로컬 포트에 제공하며 브라우저를 엽니다:

mindwalk serve [--port N] [--no-open] [--claude-dir DIR] [--codex-dir DIR]
mindwalk open [--no-open] <session.jsonl> — 특정 세션 열기
mindwalk build <repo> [-o out] — 리포지토리 시티맵 JSON 작성
mindwalk trace <session> [-o out] — 정규화된 트레이스 JSON 작성

시각화 읽기

트리 / 지형 보기 — 리포지토리를 방사형 트리 또는 트리맵으로 표시; 광도는 파일이 얼마나 깊고 자주 접근되었는지에 비례.
터치 상태 — 각 파일은 가장 깊은 터치 상태를 유지: 봄 (이끼 녹색), 읽음 (달 흰색), 편집 (따뜻한 호박색), 미방문 (어두움).
HUD 접힘 마찰 신호 — 오류율, 변경된 파일, 마지막 검증 후 편집 등을 검토 스트립으로 접음.
재생 덱 — 버킷된 히스토그램을 스크럽하거나 재생. 차가운/따뜻한 스펙트럼의 막대: 관찰(검색, 읽기, 실행)은 차갑게, 변경(편집, 검증)은 따뜻하게 빛남.
타임라인 마커 — ◇ 컨텍스트 압축, ○ 서브에이전트 시작, › 사용자 전환; 클릭하여 이동.
검사기 — 파일을 클릭하여 방문 기록 고정; 방문 행을 클릭하여 재생 헤드 이동.
키보드: Space 재생/일시정지 · ←/→ 단계 (⇧×10) · Home/End 끝 · S 속도 · E 다음 편집 · X 다음 오류 · M 다음 마커 · ⌘B 세션 레일.

내부 구조

두 개의 개별 아티팩트: 트레이스(internal/adapter의 어댑터를 통해 세션 로그에서 파일 터치 이벤트의 정규화된 스트림)와 시티맵(internal/citymap의 리포지토리 결정론적 레이아웃). 로컬 Go 서버(internal/server)가 이들을 결합하고 React/Three.js 프론트엔드(web)를 제공합니다. 스키마 계약은 schema/에 있습니다.

동일한 트리는 항상 동일한 맵을 생성하므로 세션 간 재생을 비교할 수 있습니다. 세션 데이터가 기계를 떠나지 않습니다—완전히 로컬입니다.

📖 전체 소스 읽기: HN LLM Tools