3줄 요약
- mindwalk는 Claude Code와 Codex의 세션 로그를 코드베이스의 3D “밤의 지도(night map)” 위에 재생하는 로컬 시각화 도구다.
air라이브리로드 툴로 알려진 Ricko Yu(cosmtrek)가 만들었고, 2026년 7월 9일 공개 후 열흘 만에 800스타를 넘겼다. - 문제의식은 하나다. 세션 로그는 에이전트가 무엇을 했는지는 남기지만 태스크를 어떻게 이해했는지는 남기지 않는다. mindwalk는 에이전트가 탐색하고 읽고 수정한 파일을 저장소 지도 위에 빛으로 밝혀, 그 이해의 모양을 한눈에 보이는 형태로 바꾼다.
- 단일 Go 바이너리로 완전히 로컬에서 돈다. 세션을 보는 동안에는 아무것도 외부로 나가지 않고, 사용자가 명시적으로 실행하는 세션 평가만 예외적으로 자기 계정의 CLI 모델에 요약을 보낸다.
문제 — 로그는 ‘무엇을’만 남긴다
README의 첫 문장이 이 도구의 존재 이유를 그대로 담는다.
A session log records what an agent did, but not how it understood the task. (세션 로그는 에이전트가 무엇을 했는지는 기록하지만, 태스크를 어떻게 이해했는지는 기록하지 않는다.)
저장소의 어떤 부분을 관련 있다고 봤는지, 손대기 전에 어디를 먼저 뒤졌는지, 그 발자국이 내가 생각한 범위와 맞았는지 — 날것의 JSONL을 한 줄씩 읽어서는 이 중 어느 것도 답이 나오지 않는다. 코딩 에이전트를 쓰는 사람이 실제로 궁금한 것은 이 대목인데, 로그의 형식은 그 질문에 답하도록 생기지 않았다.
아이디어 — 밤의 지도 위를 움직이는 빛
해법은 은유 하나로 요약된다. 저장소를 밤의 지도로 그리고, 세션을 그 위로 움직이는 빛으로 재생한다. 에이전트가 검색하고 읽고 수정한 곳은 지도가 빛나고, 나머지는 어둠에 잠긴다. 그러면 에이전트의 태스크 이해가 한눈에 볼 수 있는 모양이 된다.
구현의 성격도 분명하다. 하나의 Go 바이너리가 Claude Code와 Codex의 세션 로그를 읽고, 전부 로컬에서 처리하며, 세션을 보는 동안에는 아무것도 어디로도 보내지 않는다. 유일한 예외는 선택적인 세션 평가다. 이때만 세션 요약(태스크 문구, 파일 경로, 이벤트 다이제스트)이 사용자 계정 뒤의 모델로 전송된다.
그림 읽는 법
mindwalk의 화면은 여러 겹의 시각 언어로 짜여 있다.
뷰 — Tree / Terrain. 저장소를 방사형 트리로 보거나 트리맵 평면으로 본다. 빛의 세기는 파일이 얼마나 깊고 자주 만져졌는가에 비례한다.
터치 상태. 각 파일은 가장 깊은 접촉 상태를 색으로 유지한다.
| 상태 | 의미 | 색 |
|---|---|---|
| seen | 스쳐 봄 | 이끼빛 초록 |
| read | 읽음 | 달빛 파랑 |
| edited | 수정함 | 따뜻한 호박색 |
| unvisited | 방문 안 함 | 어둠 |
세션이 손댔지만 지금은 저장소에서 사라진 파일은 와이어프레임 유령(wireframe ghost)으로 남는다. HUD는 오류율, 요동친 파일 수, 마지막 검증 이후의 수정 횟수 같은 마찰 신호를 “review strip"으로 접어 보여준다.
재생 덱(Playback deck). 세션을 버킷 히스토그램 위에서 스크럽하거나 재생한다. 막대는 차가움·따뜻함 스펙트럼에 놓인다. 관찰(검색·읽기·실행)은 차갑게, 변이(수정·검증)는 따뜻하게 빛나서 편집 국면이 한눈에 튀어나온다. 재생을 .webm 비디오로 내보내는 기능도 완전히 클라이언트 쪽에서 처리한다.
타임라인 마크. ◇는 컨텍스트 압축, ○는 서브에이전트 실행, ›는 사용자 턴을 표시하고, 모든 마크는 클릭하면 그 시점으로 점프한다.
에이전트 렌즈(Agent lenses). 세션이 서브에이전트를 띄웠다면 HUD가 서브에이전트 수와 패널을 함께 싣는다. 렌즈를 골라 특정 서브에이전트의 트레이스를 같은 지도 위에서 재생하고, 다시 메인 트레이스로 빠져나올 수 있다.
인스펙터. 파일을 클릭하면 방문 이력이 고정되고, 방문 행을 클릭하면 그 순간으로 재생 헤드가 이동한다.
Repo map. mindwalk map <repo>는 세션 없이도 저장소의 시티맵을 그린다. 이때 높이는 관심도가 아니라 코드 라인 수(LOC)를 나타낸다.
키보드 단축키도 촘촘하다. Space 재생·일시정지, ←/→ 스텝(⇧와 함께 10배), Home/End 양끝, S 속도, V 뷰 전환, E 다음 수정, X 다음 오류, M 다음 마크, ⌘B 세션 레일.
세션 평가 — 명시적으로 요청할 때만
평가 패널(과 mindwalk analyze 명령)은 로컬 에이전트 CLI에게 세션의 궤적을 판정하게 한다. 탐색·범위·헤맴·검증 같은 축으로 보고, 모든 finding은 클릭해서 넘어갈 수 있는 타임라인 이벤트에 근거를 앵커한다. 판정자(설치된 아무 CLI)와 모델은 패널에서 고르고, 리포트는 실제로 누가 판정했는지를 기록한다.
무엇이 언제 기기를 떠나는지가 명확하다. 평가는 사용자 자신의 claude나 codex CLI를 실행하고, 그 세션의 요약 — 사용자 메시지 문구, 파일 경로, 한 줄 이벤트 다이제스트 — 을 계정 뒤의 모델로 보낸다. 세션을 보기만 할 때는 아무것도 나가지 않고, 다른 세션은 포함되지 않는다. 판정 서브프로세스는 봉인된(sealed) 상태로 돈다. 도구도, MCP 서버도, 사용자·프로젝트 설정도, 세션 영속화도 없다.
리포트는 ~/.mindwalk/reports에 세션당 하나씩 캐시되고, 세션 내용이 바뀌면 stale로 표시된다(자동 재실행은 하지 않는다).
내부 구조 — 의도적으로 분리한 세 산출물
mindwalk의 설계는 세 산출물을 일부러 갈라 두는 데서 나온다.
- trace (
internal/adapter) — 세션 로그를 순서 있는 파일 접촉(file-touch) 이벤트 스트림으로 정규화한다. 에이전트 포맷마다 어댑터가 하나씩(Claude Code, Codex) 붙는다. 어댑터는 서브에이전트 세션을 에이전트 그래프로 상관시켜, 각 서브에이전트의 트레이스를 독립적으로 재생할 수 있게 한다. - citymap (
internal/citymap) — 저장소의 결정론적(deterministic) 레이아웃이다. 같은 트리는 항상 같은 지도를 만든다. 그래서 서로 다른 세션의 재생을 나란히 비교할 수 있다. - report (
internal/judge) — 한 세션에 대한 LLM 판정자의 근거 앵커된 findings다. 판정자는 finding만 기여하고, verdict는 항상 기계적으로 롤업된다(finding 심각도에서 규칙으로 도출, LLM이 결정하지 않음). 그래서 리포트도 세션 간 비교가 가능하다.
로컬 Go 서버(internal/server)가 이 셋을 이어 붙여 React/Three.js 프론트엔드(web)를 서빙한다. schema/는 내보낸 JSON 계약을 미러링한다.
경계 규칙이 이 구조를 떠받친다. 어댑터는 렌더링을 모르고, 시티맵 생성은 재생에 의존하지 않으며, 판정자는 정규화된 트레이스만 읽고(날것의 세션 로그는 절대 읽지 않는다), 서버는 조각을 연결만 한다.
가장 흥미로운 지점
내가 곱씹은 대목은 판정자가 verdict를 내리지 못하도록 막아 둔 설계다. LLM은 finding — “여기서 헤맸다”, “이 파일은 검증 없이 수정됐다” 같은 근거 붙은 관찰 — 만 낼 수 있고, 그것을 종합한 최종 판정은 심각도에서 규칙으로 굴러 나온다. LLM에게 채점을 통째로 맡기면 같은 세션을 두 번 돌려도 점수가 흔들리지만, finding만 받고 롤업을 기계화하면 리포트가 세션 사이에서 비교 가능해진다. 결정론적 시티맵이 지도를 비교 가능하게 만든 것과 정확히 같은 논리를, 평가 쪽에도 한 번 더 적용한 셈이다.
두 번째는 프라이버시를 기능이 아니라 불변식으로 다룬 태도다. 판정 서브프로세스가 도구도 MCP도 설정도 없이 봉인되어 돌고, 판정에 넘기는 트레이스를 신뢰할 수 없는 입력으로 취급하며, 모든 finding이 실제 트레이스 이벤트를 인용해야 한다는 규칙이 AGENTS.md에 “지켜야 할 불변식"으로 명시되어 있다. 로컬 우선을 표방하는 도구는 많지만, 무엇이 언제 기기를 떠나는지를 이렇게 좁게 규정해 둔 경우는 드물다.
출처
Ricko Yu (cosmtrek), mindwalk — A visualization tool that replays coding-agent sessions on a 3D map of your codebase. MIT License, 2026. 원문: https://github.com/cosmtrek/mindwalk