Mindwalk: Reproduza sessões do Claude Code/Codex como trilhas de luz em um mapa de código 3D

Mindwalk é uma ferramenta de visualização que reproduz sessões de agentes de codificação em um mapa 3D do seu código. Em vez de olhar para logs brutos de sessão em JSONL, você obtém um mapa noturno onde a luz se move conforme o agente pesquisa, lê e edita — partes não tocadas permanecem escuras.

O que resolve

Um log de sessão informa o que um agente fez, mas não como ele entendeu a tarefa: quais partes do repositório tratou como relevantes, onde explorou antes de agir, ou se seu impacto correspondeu à sua intenção. Ler JSONL linha por linha não responde isso.

Início rápido

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

O instalador verifica o binário contra checksums.txt e instala em ~/.local/bin (substitua com INSTALL_DIR; fixe uma versão com VERSION). Arquivos Windows estão em GitHub Releases. Para compilar a partir do código-fonte: make setup && make build → bin/mindwalk.

Comandos

Sem argumentos, mindwalk escaneia ~/.claude/projects e ~/.codex/sessions, serve a UI em uma porta local aleatória e abre um navegador:

• mindwalk serve [--port N] [--no-open] [--claude-dir DIR] [--codex-dir DIR]
• mindwalk open [--no-open] <session.jsonl> — abre uma sessão específica
• mindwalk build <repo> [-o out] — escreve o JSON do mapa da cidade do repositório
• mindwalk trace <session> [-o out] — escreve o JSON do trace normalizado

Lendo a visualização

• Visões Árvore / Terreno — o repositório como uma árvore radial ou treemap; intensidade do brilho ∝ quão profunda e frequentemente um arquivo foi tocado.
• Estados de toque — cada arquivo mantém seu toque mais profundo: visto (verde musgo), lido (branco lua), editado (âmbar quente), não visitado (escuro).
• HUD dobra sinais de atrito — taxa de erro, arquivos alterados, edições após a última verificação — em uma faixa de revisão.
• Painel de reprodução — avance ou reproduza sobre um histograma agrupado. Barras em um espectro frio/quente: observação (pesquisa, leitura, execução) permanece fria, mutação (edição, verificação) brilha quente.
• Marcas de linha do tempo — ◇ compactações de contexto, ○ lançamentos de subagentes, › turnos do usuário; clique para pular.
• Inspetor — clique em um arquivo para fixar seu histórico de visitas; clique em uma linha de visita para pular o cursor.
• Teclado: Espaço play/pause · ←/→ passo (⇧×10) · Home/End extremos · S velocidade · E próxima edição · X próximo erro · M próxima marca · ⌘B trilha de sessão.

Sob o capô

Dois artefatos separados: um trace (fluxo normalizado de eventos de toque em arquivos a partir de logs de sessão via adaptadores em internal/adapter) e um citymap (layout determinístico do repositório em internal/citymap). Um servidor Go local (internal/server) os une e serve o frontend React/Three.js (web). Contratos de esquema estão em schema/.

A mesma árvore sempre produz o mesmo mapa, então reproduções são comparáveis entre sessões. Nenhum dado de sessão sai do seu computador — totalmente local.