cosmtrek/mindwalk

mindwalk

코딩 에이전트 세션을 코드베이스의 3D 지도 위에서 재생하는 시각화 도구입니다.

문제

세션 로그는 에이전트가 무엇을 했는지는 기록하지만, 에이전트가 태스크를 어떻게 이해했는지는 기록하지 않습니다. 저장소의 어떤 부분을 관련 있다고 여겼는지, 행동하기 전에 어디를 탐색했는지, 그 발자취가 사용자가 염두에 둔 범위와 일치했는지 등이 그것입니다. 원시 JSONL을 줄 단위로 읽는 것만으로는 이러한 질문에 답할 수 없습니다.

아이디어

저장소를 밤의 지도로 그리고, 세션을 그 위를 이동하는 빛으로 재생합니다. 에이전트가 검색하고, 읽고, 편집한 곳은 지도가 빛나고, 나머지는 어둠 속에 남습니다. 에이전트의 태스크 이해는 한눈에 볼 수 있는 형태가 됩니다. 하나의 Go 바이너리가 Claude Code, Codex, pi 세션 로그를 읽으며, 완전히 로컬에서 동작합니다. 조회 시 어떤 곳으로도 데이터를 보내지 않습니다. 유일한 예외는 선택적인 세션 평가입니다. 명시적으로 실행하면 해당 세션의 요약(태스크 문구, 파일 경로, 이벤트 요약)이 사용자 자신의 claude 또는 codex CLI 뒤에 있는 모델로 전송됩니다. 세션 평가 섹션을 참조하세요.

빠른 시작

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.

>[!TIP] >Nix 사용자는 numtide/llm-agents flake를 통해 mindwalk를 추가할 수 있습니다.

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

mindwalk serve [--port N] [--no-open] [--claude-dir DIR] [--codex-dir DIR] [--pi-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] [--no-rubric]
                                            evaluate one session (see below)

그림 읽기

• 트리/지형 뷰(Tree / Terrain views) — 저장소를 방사형 트리 또는 일반 트리맵으로 표시합니다. 파일이 얼마나 깊이, 얼마나 자주 접촉되었는지에 비례하여 빛이 납니다.
• 터치 상태(Touch states) — 각 파일은 가장 깊은 터치 상태를 유지합니다: 본(이끼 녹색), 읽음(달빛 파란색), 편집(따뜻한 호박색), 미방문(어두운색). 세션이 접촉했지만 더 이상 저장소에 없는 파일은 와이어프레임 유령으로 남습니다. HUD는 오류율, 반복 수정된 파일, 마지막 검증 이후의 편집 같은 마찰 신호를 리뷰 스트립으로 접어서 보여줍니다.
• 재생 덱(Playback deck) — 실행의 버킷 히스토그램 위에서 세션을 스크러빙하거나 재생합니다. 막대는 차가운/따뜻한 스펙트럼 위에 놓입니다: 관찰은 차갑게 유지되고(검색, 읽기, 실행), 변경은 따뜻하게 빛납니다(편집, 검증). 따라서 편집 단계가 한눈에 드러납니다. 다시 시작, 속도, 비디오 내보내기는 덱의 ⋯ 메뉴에 들어 있습니다. 내보내기는 재생을 완전히 클라이언트 측에서 .webm으로 기록합니다.
• 타임라인 마커(Timeline marks) — ◇는 컨텍스트 압축, ○는 서브에이전트 실행, ›는 사용자 턴을 나타냅니다. 모든 마커는 클릭하면 해당 시점으로 이동합니다.
• 에이전트 렌즈(Agent lenses) — 세션이 서브에이전트를 실행한 경우 HUD에 서브에이전트 수와 에이전트 패널이 표시됩니다. 렌즈를 선택하면 같은 지도에서 서브에이전트의 트레이스를 재생하고, 다시 메인 트레이스로 돌아올 수 있습니다.
• 인스펙터(Inspector) — 파일을 클릭하면 해당 파일의 방문 기록을 고정할 수 있고, 방문 행을 클릭하면 재생 헤드를 그 시점으로 이동합니다.
• 평가(Evaluate) — 로컬 에이전트 CLI에 세션의 궤적을 판정하도록 요청합니다. 자신의 요청에서 작성된 기준에 따라 점수가 매겨지며, 세션 행에는 평가 상태가 은은한 배지로 표시됩니다. 세션 평가 섹션을 참조하세요.
• 저장소 지도(Repo map) — mindwalk map (또는 세션 레일의 폴더 아이콘)은 세션 없이도 임의 저장소의 시티맵을 렌더링합니다. 높이는 주목도 대신 코드 줄 수를 나타냅니다.

키보드: Space 재생/일시정지 · ←/→ 단계 이동(⇧ ×10) · Home/End 처음/끝 · S 속도 · V 뷰 · E 다음 편집 · X 다음 오류 · M 다음 마커 · ⌘B 세션 레일.

세션 평가

평가 패널(및 mindwalk analyze)은 로컬 에이전트 CLI에 세션이 어떻게 진행되었는지 판정하도록 요청합니다. 보고서는 두 개의 층으로 구성됩니다:

• 프로세스 차원(Process dimensions) — 탐색, 범위, 방황, 검증: 모든 세션에 동일하게 적용되는 네 가지 고정 렌즈로, 보고서 간 비교가 가능합니다.
• 태스크 스코어카드(Task scorecard) — 점수를 매기기 전에 판정자가 사용자 요청 문구에서 기준을 작성합니다. 이 태스크에서 무엇을 완료로 볼 것인지가 기준이 되며, 세션에 여러 태스크가 있을 때는 태스크별로 그룹화됩니다. 이후 각 기준은 차원과 함께 한 번의 패스로 세션에 대해 점수가 매겨집니다.

두 층의 모든 소견은 클릭하여 이동할 수 있는 타임라인 이벤트를 인용해야 하며, 어떤 판정도 모델이 결정하지 않습니다. 차원 및 기준 판정은 소견의 심각도에서 기계적으로 집계됩니다. 로그가 기준 충족 여부를 보여줄 수 없는 경우 해당 커버리지는 낮아지고 판정은 "신호 없음(no signal)"으로 표시됩니다. 검증할 수 없는 기준은 실패가 아니라 맹점입니다. 패널에서 판정자(설치된 임의의 CLI)와 모델을 선택할 수 있으며, 보고서에는 실제로 판정한 주체가 기록됩니다.

스코어카드는 흐름을 방해하지 않도록 비켜서 있습니다. 도구 이벤트가 없거나 태스크 텍스트가 너무 적은 세션은 이를 건너뛰고, 기준 작성에 실패하면 차원 전용 보고서로 대체됩니다. --no-rubric(또는 analyze API의 "rubric": false)을 사용하면 단일 판정 호출로 명시적으로 건너뜁니다. 스코어카드가 어떻게 구성되는지, 그리고 왜 그런 형태를 가지는지는 docs/dynamic-rubric-evaluation.md에 설명되어 있습니다.

무엇이 머신을 떠나는가 — 그리고 오직 요청할 때만: 평가는 사용자 자신의 claude 또는 codex CLI를 실행합니다. 최대 두 번의 격리된 호출로, 하나는 기준 작성, 하나는 점수 매기기입니다. 두 호출 모두 해당 세션의 요약(사용자 메시지의 문구, 파일 경로, 한 줄 이벤트 요약)만 사용자 계정 뒤의 모델로 보냅니다. 세션을 조회하는 동안에는 아무것도 전송되지 않으며, 다른 세션은 포함되지 않습니다. 판정 하위 프로세스는 격리된 상태로 실행됩니다: 도구 없음, MCP 서버 없음, 사용자/프로젝트 설정 없음, 세션 영속화 없음.

보고서는 세션별로 ~/.mindwalk/reports에 캐시됩니다. 세션 내용이 변경되면 보고서는 오래된 것으로 표시됩니다(자동으로 다시 실행되지 않음). 태스크 문구가 변경되지 않은 세션을 재평가하면 작성된 기준이 재사용됩니다. 점수는 움직일 수 있어도 측정 기준은 변하지 않습니다.

내부 구조

의도적으로 분리된 세 가지 산출물이 있습니다:

1. 트레이스(trace) — 세션 로그를 파일 터치 이벤트의 정렬된 스트림으로 정규화한 것입니다(internal/adapter, 에이전트 형식별 어댑터 하나씩). 어댑터는 또한 서브에이전트 세션을 에이전트 그래프로 연관 지어, 각 서브에이전트의 트레이스를 독립적으로 재생할 수 있게 합니다.
2. 시티맵(citymap) — 저장소의 결정적(deterministic) 레이아웃입니다(internal/citymap). 같은 트리는 항상 같은 지도를 생성하므로 세션 간 재생 결과를 비교할 수 있습니다.
3. 보고서(report) — LLM 판정자가 한 세션에 대해 증거에 기반해 작성한 소견입니다(internal/judge). 네 가지 고정 프로세스 차원과 태스크별 스코어카드로 구성됩니다. 판정자는 소견만 제공하며 판정은 항상 기계적으로 집계되므로 보고서도 비교 가능합니다.

로컬 Go 서버(internal/server)가 이들을 결합하고 React/Three.js 프론트엔드(web)를 제공합니다. schema/는 내보내진 JSON 계약을 미러링합니다.

make setup   # 프론트엔드 의존성 설치
make serve   # :8765에서 개발 서버 실행, 작업 트리의 web/dist 제공
make test    # go test + 프론트엔드 빌드 — PR 보내기 전에 실행
make build   # 임베디드 에셋과 bin/mindwalk 재생성