Cos’è successo. Mindwalk è un visualizzatore locale che legge i log di sessione di Claude Code e Codex e li riproduce su una mappa 3D della repository: ogni file diventa un punto nello spazio, e l’attività dell’agente (ricerca, lettura, modifica) accende quella zona della mappa. Un Go binary scaricabile, tutto locale, nessun dato inviato fuori macchina. Il progetto è su GitHub con licenza MIT.

Perché ti riguarda. Quando deleghi un compito a un agente di coding, il log JSONL ti dice cosa ha fatto, non come ha capito il problema: quali parti del repo ha esplorato, dove si è concentrato, se il suo percorso corrisponde a quello che avevi in mente. Mindwalk trasforma quella sequenza in una forma che puoi vedere in un colpo d’occhio: la comprensione del task dell’agente diventa una mappa di calore sulla codebase. Se l’agente ha toccato file che non c’entrano niente, o se ha saltato quelli centrali, lo vedi subito. È utile per debuggare agenti che falliscono (dove si è perso?) e per migliorare i prompt (gli ho dato abbastanza contesto sulla struttura?).

Se vuoi provarci. Il repo contiene uno script di installazione che verifica la firma e installa il binario in ~/.local/bin. Una volta installato, mindwalk senza argomenti legge le cartelle di Claude Code e Codex e apre l’interfaccia web in locale. La UI ha una timeline a istogramma (azioni di osservazione vs mutazione), controlli per play/pausa e scrub, e un inspector che mostra la storia di visite di ogni file cliccato.

Nel dettaglio

Il contesto

Gli agenti di coding — Claude Code, Codex, Cursor in modalità agente — producono log dettagliati di ogni azione (file aperti, ricerche, modifiche, esecuzioni). Ma leggere un JSONL linea per linea non risponde alla domanda più importante: l’agente ha capito il problema come tu te lo immaginavi? Ha esplorato le parti giuste del repo, o si è concentrato su zone che non c’entrano?

Mindwalk parte dall’idea che la comprensione di un task da parte dell’agente ha una forma spaziale: si può rappresentare come una mappa di luce e ombra sulla codebase. Dove l’agente ha cercato, letto e modificato, la mappa si accende; tutto il resto resta buio.

Come funziona

Il tool ha due modalità principali:

• Serve mode (mindwalk senza argomenti): scansiona le cartelle di Claude Code (~/.claude/projects) e Codex (~/.codex/sessions), genera le mappe delle repository coinvolte, avvia un server locale su porta casuale e apre il browser. Da lì puoi scegliere una sessione dalla lista e vederne il replay.
• Open mode (mindwalk open <session.jsonl>): apre una sessione specifica senza scansionare tutto.

La rappresentazione visiva offre due viste: Tree (albero radiale della struttura delle cartelle) e Terrain (treemap piano, ogni file è un rettangolo dimensionato per numero di visite). Ogni file porta uno stato di touch che evolve con la sessione: seen (verde muschio, file incontrato in una ricerca), read (bianco lunare, file aperto), edited (ambra calda, file modificato), unvisited (scuro). Lo stato tiene traccia del livello più profondo raggiunto.

L’istogramma della timeline sotto la mappa mostra l’attività della sessione in bucket temporali su uno spettro freddo/caldo: azioni di osservazione (search, read, exec) restano fredde, mutazioni (edit, verify) si scaldano. Le fasi di editing saltano fuori visivamente. Sulla timeline compaiono marker cliccabili: compattazioni di contesto (◇), lanci di sottoagenti (○), turni utente (›).

L’HUD in alto riepiloga segnali di friction: tasso di errore, file modificati più volte (churn), modifiche dopo l’ultima verifica. L’inspector a lato si apre cliccando un file e mostra la sua storia di visite con timestamp; ogni riga è un salto della playhead a quel momento.

I limiti

Mindwalk lavora solo sui log che i tool producono. Se un agente tiene conversazioni interne o fa ragionamenti che non finiscono nel log strutturato, quelli restano invisibili. La mappa mostra dove l’agente è andato, non perché: per ricostruire il ragionamento devi comunque rileggere i messaggi della sessione.

Il tool per ora supporta solo Claude Code e Codex. Altri agenti di coding (Cursor, Windsurf, Zed AI) producono log in formati diversi: servirà un parser per ognuno, o uno standard condiviso (non esiste ancora).

Infine, la visualizzazione 3D è utile per repository di dimensioni medio-piccole. Su monorepo enormi (migliaia di file) la mappa diventa difficile da navigare: il tool non scala ancora bene oltre una certa soglia.

Cosa farne

Mindwalk non ti dice se l’agente ha fatto un buon lavoro: ti dice se ha capito il problema come te. Se un task di refactoring ha toccato solo metà dei file che sapevi essere coinvolti, hai scoperto un problema nel brief o nel contesto passato. Se l’agente ha modificato file di config che non c’entravano niente, hai scoperto un tool chiamato al momento sbagliato o un prompt ambiguo.

È uno strumento di debugging del prompt, non del codice prodotto. Dopo aver visto la mappa, torni al brief dell’agente e lo riscrivi con il contesto mancante, o delimiti meglio i confini degli strumenti.

Per chi costruisce agenti custom o fa esperimenti con orchestrazioni multi-agente, Mindwalk può diventare parte del ciclo di sviluppo: giri il task, guardi la mappa, correggi, rilanci. È lo stesso loop che fai con un profiler di performance, ma applicato alla comprensione del task invece che al tempo di esecuzione.