Mindwalk – 코딩 에이전트 세션을 코드베이스 3D 맵 위에서 재생하는 시각화 도구

Who Should Read

Claude Code나 Codex 같은 AI 코딩 에이전트를 실무에 쓰는 개발자 중, 에이전트가 세션 중 어떤 파일을 건드렸는지 추적하거나 에이전트의 의사결정 흐름을 시각적으로 이해하고 싶은 분. 특히 대규모 레포에서 에이전트의 탐색 범위가 의도와 맞는지 검토하고 싶은 경우에 유용하다.

Core Mechanics

• AI 코딩 에이전트 세션 로그(JSONL 파일)는 에이전트가 무엇을 했는지는 기록하지만, '왜 그 부분을 중요하게 봤는지', '실제 작업 범위가 의도와 맞는지'는 원본 텍스트만으로는 파악하기 어렵다. Mindwalk는 이 문제를 시각화로 해결한다.
• 레포지토리를 야경 지도처럼 렌더링한 뒤, 에이전트가 검색·읽기·편집한 파일 위치에 빛이 켜지는 방식으로 세션을 재생한다. 에이전트가 실제로 관심을 가진 영역이 어디인지 형태로 보인다.
• Claude Code의 세션 로그(~/.claude/projects)와 Codex의 세션 로그(~/.codex/sessions)를 자동으로 스캔해서 지원한다. 두 에이전트 모두 커버된다.
• 완전히 로컬에서 동작하는 단일 Go 바이너리로 제공된다. 세션 데이터가 외부 서버로 전송되지 않아 보안 측면에서 안전하다.
• curl 한 줄로 설치하고 mindwalk만 실행하면 랜덤 로컬 포트로 UI가 뜨고 브라우저가 자동으로 열린다. 별도 설정 없이 바로 쓸 수 있다.
• mindwalk serve, mindwalk open <session.jsonl>, mindwalk build <repo>, mindwalk trace <session> 등 CLI 명령어를 지원한다. 특정 세션 파일만 열거나, 레포 맵 JSON을 별도로 추출하는 것도 가능하다.
• Tree 뷰와 Terrain 뷰 두 가지 방식으로 레포 구조를 시각화할 수 있다. Timeline 기능도 있어서 시간 순서대로 에이전트의 파일 접근 내역을 확인할 수 있다.
• 소스 빌드도 지원하며 make setup && make build 명령으로 bin/mindwalk 바이너리를 직접 빌드할 수 있다. Windows는 GitHub Releases에서 아카이브를 받을 수 있다.

Evidence

• 같은 문제(코드베이스를 두 개의 다른 모델이 어떻게 다르게 탐색하는지 비교)를 시각화하거나, 같은 모델을 100번 실행했을 때 평균적으로 어떤 파일을 건드리는지 분산을 보는 것도 흥미로운 활용 케이스가 될 것이라는 의견이 있었다. 모델 평가나 에이전트 행동 분석 도구로 확장 가능성이 있다는 시각이다.
• 에이전트 UI의 장기적 방향이 결국 공간적(spatial) 표현이 될 것이라는 의견도 있었다. 터미널에서 'Read file: xyz' 텍스트만 스크롤하는 것은 실제로 에이전트가 어디서 정보를 가져오는지 파악하기 어려운데, Mindwalk처럼 시각적으로 보여주는 방식이 그 갭을 메운다는 평가다.
• 실제로 작은 프로젝트로 테스트해봤는데 Timeline에는 파일 읽기/쓰기 이벤트가 보이지만, Tree/Terrain 뷰에서는 아무것도 표시되지 않는다는 버그 리포트가 있었다. 프로젝트 폴더가 로컬에 존재하지 않는 경우 Tree 뷰가 렌더링되지 않는 것으로 보이며, 이 경우 레포 경로가 필요한지 묻는 질문도 달렸다.
• 세션별 히스토리만 보이고, 모든 에이전트 세션을 통합해서 누적 히스토리를 보는 기능이 없다는 피드백이 있었다. 에이전트를 여러 세션에 걸쳐 사용하는 경우 전체적인 작업 흐름을 파악하기 어렵다는 지적이다.
• 유사한 접근으로 바이너리 로그(binlog)에 파일 변경 내역을 저장해서 핫 파일 경로 추적, 부분 롤백 등 운영 목적으로 쓰는 구현을 공유한 사람도 있었다. 파일 변경 조회 속도가 3~5ms이며, 사이드 에이전트로 위험 구간을 실시간 분석하는 데 활용 중이라고 했다.

How to Apply

• Claude Code로 대형 레포를 리팩터링한 뒤 에이전트가 실제로 어떤 파일들을 탐색했는지 확인하고 싶다면, curl로 mindwalk를 설치한 뒤 mindwalk만 실행하면 된다. ~/.claude/projects 아래 세션 로그를 자동으로 스캔해서 3D 맵 위에 에이전트 동선을 시각화해준다.
• 특정 세션만 빠르게 검토하고 싶다면 mindwalk open <session.jsonl> 명령으로 단일 JSONL 파일을 직접 열 수 있다. 에이전트가 작업 범위를 과도하게 넓혀서 불필요한 파일까지 탐색했는지 확인하는 데 유용하다.
• 같은 작업을 서로 다른 모델(예: Claude Code vs Codex)로 실행한 뒤 각 세션의 3D 맵을 비교하면, 두 에이전트가 레포를 이해하는 방식의 차이를 시각적으로 확인할 수 있다. 어떤 모델이 더 범위를 적절히 좁혀서 탐색하는지 직관적으로 평가할 수 있다.
• mindwalk build <repo> 명령으로 레포 구조를 citymap JSON으로 추출하고, mindwalk trace <session>으로 정규화된 trace JSON을 별도로 뽑아낼 수 있다. 이 파일들을 파이프라인에 통합하면 에이전트 세션 분석을 자동화하거나 다른 도구와 연동하는 데 활용할 수 있다.

Code Example

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

# 기본 실행 (~/.claude/projects와 ~/.codex/sessions 자동 스캔)
mindwalk

# 포트 지정 + 브라우저 자동 오픈 비활성화
mindwalk serve --port 8080 --no-open

# 특정 세션 파일 하나만 열기
mindwalk open <session.jsonl>

# 레포 citymap JSON 추출
mindwalk build <repo> -o citymap.json

# 세션 정규화 trace JSON 추출
mindwalk trace <session> -o trace.json

# 소스 빌드
make setup && make build
# → bin/mindwalk 생성

Terminology

관련 논문

• Ghost Font: 사람은 읽을 수 있지만 AI는 읽기 어려운 안티-AI 폰트 실험

  움직임(모션)을 이용해 글자를 표현해서 AI 모델이 정적 이미지 분석으로는 메시지를 해독하지 못하게 막는 실험적 프로젝트인데, 커뮤니티에서는 이미 GPT-5.6, Claude Opus 등으로 해독에 성공한 사례가 속출해 실효성 논쟁이 뜨겁다.

• GPT-5.6, Grok 4.5, Claude, Muse Spark 등 12개 모델이 동일한 앱 4개를 빌드한 결과 비교

  12개 LLM 모델에게 레이캐스터 미로, 루빅스 큐브, 계산기, Game of Life 앱을 각각 5번씩 만들게 해서 성공률·비용·속도를 비교한 실전 벤치마크다. GPT-5.6 Sol이 전반적으로 가장 일관된 결과를 냈고, Grok 4.5는 가성비 면에서 눈에 띄었다.

• Databricks가 수백만 라인 실제 코드베이스로 Coding Agent를 벤치마킹한 결과

  Databricks가 자사 실제 코드베이스를 기반으로 여러 AI 코딩 에이전트의 성능과 비용을 직접 측정했고, 모델 토큰 가격과 실제 태스크 비용이 전혀 다르다는 점, 그리고 오픈소스 모델이 이제 최상위 수준에 도달했다는 점을 확인했다.

• Reasoning에서 Uncertainty 추정하기: LLM의 다국어 및 교차언어 MCQA 성능 대규모 연구

  LLM이 저자원 언어 질문을 받을 때 영어로 추론하게 하면 불확실성 추정 성능이 고자원 언어 수준으로 올라온다.

• LLM-as-a-Verifier: 범용 Verification 프레임워크

  LLM의 토큰 확률 분포를 활용해 discrete 점수 대신 continuous 점수를 뽑아내면, 추가 학습 없이 코딩·로봇·의료 에이전트 평가 정확도를 SOTA로 끌어올릴 수 있다.

• 코드 품질이 Coding Agent 성능에 영향을 미치는가? Minimal-Pair 통제 실험 연구

  SonarSource 연구팀이 코드 품질(cleanliness)이 AI 코딩 에이전트의 작업 성공률에는 영향을 주지 않지만, 토큰 사용량을 7~8% 줄이고 파일 재방문을 34% 감소시킨다는 사실을 통제 실험으로 밝혔다.

Related Resources

• Mindwalk GitHub 레포지토리
• glyph3d.dev – 파일을 블록 대신 글리프(문자 단위) 렌더링으로 시각화하는 유사 도구
• haicue-brew 스크립트 – 파일 변경 binlog 기반 에이전트 세션 추적 도구