TL;DR

mindwalk는 코드 저장소를 결정론적 3D 맵으로 렌더링하고 Claude Code와 Codex 로그를 정규화한 trace를 통해 에이전트 세션을 재생하는 로컬 툴이다. 재생 데크와 색상 스펙트럼으로 검색·읽기·편집 구간을 시각적으로 구분할 수 있고, 서브에이전트 렌즈 전환과 방문 이력 고정으로 상세 원인 추적이 가능하다. 평가 기능은 사용자가 로컬 claude/codex CLI를 명시적으로 실행할 때만 세션 요약을 전송해 리포트를 생성하며 모든 뷰잉은 로컬에서 유지된다.

해결 문제

원시 JSONL 로그를 라인별로 읽어서는 에이전트가 코드베이스에서 무엇을 중요하게 봤는지, 어느 구간을 탐색했는지, 실제 편집 범위가 의도 범위와 맞는지 파악하기 어렵다. mindwalk는 저장소를 3D 맵으로 시각화하고 검색·읽기·편집 이벤트를 색과 높이로 매핑해 에이전트의 이해지도를 눈으로 확인할 수 있게 만든다. 그 결과 코드 리뷰어나 개발자는 세션의 탐색 경로, 검증 누락, 편집 집중 구간을 빠르게 식별할 수 있다.

주요 기능

• 로컬 전용 재생과 선택적 판단 기능을 제공한다. 세션 열람 중에는 외부 전송이 없고, 평가 기능은 사용자가 명시적으로 로컬 claude 또는 codex CLI를 실행할 때만 요약을 전송한다. 이 설계는 개인정보와 코드베이스를 외부에 노출하지 않으려는 워크플로우에 적합하다.
• 다중 에이전트 형식을 어댑터로 정규화해 재생할 수 있다. Claude Code와 Codex 로그를 internal/adapter로 파싱해 동일한 trace 스키마로 합치므로 서브에이전트별 렌즈 전환과 비교 분석이 가능하다. 동일한 저장소 레이아웃에서 재생 결과가 비교 가능하도록 citymap은 결정론적 레이아웃을 사용한다.
• 브라우저 기반의 대화형 UI와 클라이언트 측 비디오(export .webm) 기능을 포함한다. 재생 데크에서 속도, 구간 스크럽, 마커 점프, 에이전트 필터링을 제어할 수 있으며 클라이언트에서 직접 웹M으로 녹화해 외부 공유 자료를 생성할 수 있다.

차별점

• 완전 로컬 우선 워크플로우를 채택한다. 세션 열람 단계에서는 어떤 데이터도 외부로 전송하지 않으며, 평가 기능도 사용자가 명시적으로 로컬 Claude/Codex CLI를 호출할 때만 요약을 전송한다. 이 구조는 민감 코드베이스에 대한 시각화·검토를 조직 환경에서 안전하게 수행할 수 있게 만든다.
• 에이전트 포맷별 어댑터와 결정론적 citymap을 분리해 재현성과 비교 가능성을 보장한다. adapter는 로그를 동일한 trace 스키마로 정규화하고 citymap은 동일 트리에서 항상 같은 레이아웃을 생성하므로 서로 다른 세션 간 시각적 비교가 신뢰할 수 있다. 이로 인해 에이전트 업데이트 전후의 행동 변화를 일관되게 추적할 수 있다.
• 프런트엔드에서 직접 재생 녹화(.webm)를 생성하고 에이전트 렌즈 전환·마커 점프 등 대화형 검토 도구를 제공한다. 재생 덱의 시간-버킷 뷰와 색상 스펙트럼은 관찰 단계와 변이 단계의 구간을 빠르게 구분하게 하며, 파일 클릭으로 방문 이력에 즉시 점프할 수 있어 실무 검토 효율을 높인다.

지금 주목받는 이유

레포지토리에는 시각적 검토 도구라는 명확한 문제-해결 관계와 사용자가 즉시 시도할 수 있는 설치 스크립트가 있어 빠르게 관심을 끌었다. README에 Claude Code·Codex 호환성, 로컬 우선 설계, 웹 기반 재생 및 비디오 내보내기 기능이 명시되어 있어 에이전트 도입 초기 단계의 디버깅·감사 수요와 맞물렸다. 공개된 스타 수(1122개)와 데모 스크린샷은 커뮤니티에서 검토·디버깅 도구로 실용성이 인정받았음을 시사한다.

어떻게 동작하는가

mindwalk는 세 가지 아티팩트를 분리해 동작한다: adapter가 다양한 에이전트 로그를 정규화해 순서화된 trace 이벤트 스트림을 만든다, citymap 모듈은 저장소 트리를 결정론적으로 3D 레이아웃으로 변환해 동일 트리에서 일관된 맵을 생성한다, judge 모듈은 선택적 평가를 위해 이벤트 근거를 묶은 리포트를 생성한다. 내부 Go 서버가 이들 아티팩트를 조인하고 React/Three.js 프런트엔드에 제공하므로 사용자는 로컬 브라우저에서 재생·검색·파일별 이력 고정을 할 수 있다. 평가 실행은 사용자가 판정자를 선택해 로컬 claude 또는 codex CLI를 직접 호출하는 방식으로 이루어져, 해당 요약만 모델로 보내고 보고서는 ~/.mindwalk/reports에 캐시된다.

사용 사례

• 자동화된 에이전트가 만든 변경을 코드 리뷰 관점에서 검사할 때 유용하다. 재생으로 에이전트의 탐색 경로와 편집 집중 지점을 시각적으로 파악할 수 있으므로 리뷰어는 의도와 다른 편집이나 검증 누락을 빠르게 찾아낼 수 있다. 특히 서브에이전트가 많은 복합 세션에서 부분별 렌즈를 전환해 세부 행위를 분리해 검토할 수 있다.
• 에이전트 개발자가 정책·프롬프트 변경이 행동에 미치는 영향을 디버깅할 때 사용할 수 있다. 결정론적 citymap과 정규화된 trace 덕분에 서로 다른 세션을 일관되게 비교할 수 있어 변경 전후의 탐색·편집 패턴 차이를 식별하기 쉽다. 또한 실행·편집 타이밍과 오류 발생 지점을 타임라인에서 곧바로 좁혀 문제 원인을 분석할 수 있다.
• 보안·감사 목적으로 에이전트 행동 이력을 보관·조회할 때 적합하다. 세션 단위로 근거가 연결된 리포트를 생성하고 로컬에 캐시하므로 외부 서버에 민감 정보를 남기지 않고도 사건 재구성이 가능하다. 파일이 삭제된 경우에도 wireframe ghost로 과거 터치를 표시해 이력을 추적할 수 있다.

시작하기

빠른 시작은 제공된 install.sh를 파이프라인으로 내려받아 실행하는 것으로, 스크립트는 바이너리 체크섬을 검증해 ~/.local/bin에 설치한다. 개발자는 make setup && make build로 소스에서 빌드해 bin/mindwalk를 생성할 수 있고, 기본 명령어로는 serve, open, map, build, trace, analyze 등이 제공된다. 기본 동작은 ~./claude/projects와 ~/.codex/sessions를 스캔해 로컬 포트로 UI를 제공하고 브라우저를 여는 방식이다.

요구사항

• Go 언어 도구체인(소스 빌드 시).
• 웹 브라우저(React/Three.js 프런트엔드를 렌더링할 수 있는 환경).
• 선택적: 로컬 claude 또는 codex CLI(세션 평가 기능을 사용할 때 필요).

이미지 분석