Mindwalk: AI 코딩 에이전트 세션을 3D로 시각화하기

Mindwalk: AI 코딩 에이전트 세션을 3D로 시각화하기

Mindwalk는 세션 로그를 저장소(repository)의 3D 지도로 재생하여 AI 코딩 에이전트를 감사(auditing)할 수 있는 공간적 방법을 제공합니다. 표준 세션 로그가 에이전트가 무엇을 했는지 기록하는 반면, Mindwalk는 에이전트가 작업을 어떻게 이해했는지, 특히 어떤 파일을 관련이 있다고 판단했는지, 그리고 행동하기 전에 어디를 탐색했는지를 시각화합니다.

에이전트 행동의 공간적 분석

Mindwalk는 저장소를 에이전트의 활동이 빛을 만들어내는 "의 밤 지도(night map)"로 변환합니다. 이를 통해 개발자는 에이전트의 발자취를 한눈에 파악하여, 에이전트의 탐색이 작업의 의도된 범위와 일치하는지 확인할 수 있습니다.

시각화 모드 및 지표

  • Tree and Terrain Views: 코드베이스는 방사형 트리(radial tree) 또는 트리맵(treemap) 평면으로 표현됩니다. 빛의 강도는 파일이 얼마나 깊고 빈번하게 다루어졌는지를 나타냅니다.
  • Touch States: 파일은 가장 깊은 수준의 상호작용에 따라 색상으로 구분됩니다:
    • Moss Green: Seen (확인됨)
    • Moon White: Read (읽음)
    • Warm Amber: Edited (수정됨)
    • Dark: Unvisited (방문하지 않음)
  • Playback Deck: 버킷형 히스토그램을 통해 사용자가 세션을 스크러빙(scrubbing)할 수 있습니다. 관찰 단계(search, read, exec)는 차가운 색상으로 표시되고, 변이 단계(edit, verify)는 따뜻한 색상으로 빛납니다.
  • Timeline Marks: 특정 기호가 주요 이벤트를 표시합니다: ◇는 context compaction, ○는 subagent launch, ›는 user turn을 나타냅니다.

기술적 아키텍처

Mindwalk는 로컬 Go binary로 구축되어 세션 데이터가 사용자의 기계에서 외부로 유출되지 않음을 보합니다합니다. 데이터는 두 가지 별개의 아티팩트로 분리됩니다:

  1. The Trace: 어댑터를 통해 세션 로그에서 파생된 파일 터치(file-touch) 이벤트의 정규화된 스트림입니다. 현재 Claude Code와 Codex 세션 로그를 지원합니다.
  2. The Citymap: 저장소의 결정론적 레이아웃입니다. 동일한 트리는 항상 동일한 지도를 생성하므로, 서로 다른 세션 간의 재생이 가능합니다.

시스템은 로컬 Go server를 사용하여 trace와 citymap을 결합하고, React와 Three.js로 구축된 프론트엔드를 제공합니다.

설치 및 사용법

Mindwalk는 쉘 스크립트나 Makefile을 사용하여 소스에서 빌드할 수 있습니다.

Quick Start:

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

Core Commands:

  • mindwalk serve: ~/.claude/projects와 ~/.codex/sessions를 스캔하고 로컬 포트에서 UI를 제공합니다.
  • mindwalk open <session.jsonl>: 특정 세션 로그를 엽니다.
  • mindwalk build <repo>: 저장소의 citymap JSON을 생성합니다.
  • mindwalk trace <session>: 정규화된 trace JSON을 작성합니다.

커뮤니티 인사이트 및 사용 사례

일부 사용자는 전통적인 diff와 비교하여 3D 시각화의 즉각적인적인 유용성에 의문을 제기했지만, 다른 사용자들은 공간적 에이전트 감사(auditing)를 위한 잠재적인 고가치 사용 사례를를 강조했습니다:

"하나의 멋진 기능은 일종의 공간적/표현된 비교가 될 것입니다: 서로 다른 두 모델이 (동일한 문제에 대해) 코드베이스와 어떻게 상호작용하는지, 무엇을 건드렸는지, 그리고 무엇을 했는지 살펴보는 것입니다."

다른 커뮤니티 멤버들은 터미널 기반의 "Read file" 로그가 종종 따라가기 어렵다는 점을 언급하며, 공간적 표현이 LLM이 정보를 어디에서 가져오는지 정확히 식별별하는 데 도움이 된다고 말했습니다. 일부 사용자는 도구를 확장하여 세션별 기록이 아닌 모든 에이전트의 누적적 히스토리를 제공하도록 제안했습니다.

Sources