Mycelium: la mappa che mancava ai tuoi agenti AI

Ti è mai capitato di guardare il tuo agente AI mentre lavora e chiederti dove sia finita la sua brillantezza? Apre un file, poi un altro, poi altri dieci. Venti minuti dopo ha consultato quaranta file, non ricorda più la metà, e propone modifiche che ignorano completamente come è strutturato il tuo progetto.

Se ti riconosci, sappi che non sei solo. È uno dei problemi più fastidiosi dello sviluppo assistito da AI al momento — e proprio questo vuole risolvere Mycelium.

Il problema del contesto

Il punto è semplice: gli agenti AI sono buoni quanto il contesto che gli dai. Fornisci le informazioni giuste e scriveranno codice elegante e preciso. Buttali in mezzo a una valanga di file irrilevanti e produrranno spaghetti che richiedono una riscrittura completa.

Il guaio è che la maggior parte degli strumenti AI parte praticamente da zero. Non sanno quali file gestiscono l'autenticazione, quali contengono la logica di business, quali sono codice legacy da non toccare. Così provano a indovinare. Apre i file in ordine alfabetico, o per ordine di import, o seguendo qualche euristica casuale. È lento, inefficiente, e spesso completamente inutile.

Arriva Mycelium

Mycelium prende un'altra strada. Invece di lasciare che il tuo agente giri per il codebase alla cieca, crea una mappa completa del progetto — ogni file, ogni dipendenza, ogni connessione tra loro. Quando il tuo agente deve fare una modifica, interroga questa mappa e ottiene esattamente i file che servono, con spiegazioni in italiano di cosa fa ciascuno.

Il funzionamento è disarmante nella sua semplicità. Esegui npx @kopikocappu/mycelium init una volta sola, e Mycelium analizza tutto il codebase, risolve gli import e costruisce un dependency graph. Usa anche un modello AI leggero (Claude Haiku) per scrivere descrizioni di ogni file in linguaggio naturale.

Poi, prima che il tuo agente attacchi qualsiasi task, chiama /preflight con una descrizione di cosa deve fare. Mycelium ritorna i quattro file che contano davvero — non quaranta.

Più di una semplice ricerca file

Ma Mycelium va oltre il lookup di file. Include diverse funzionalità che lo rendono davvero utile per i team:

Il graph viewer live ti permette di visualizzare tutto il codebase nel browser. I file diventano nodi, gli import diventano archi, e puoi vedere l'architettura del progetto d'occhio. Per un nuovo sviluppatore che entra in un progetto, questa funzionalità da sola ripaga il tempo di setup.

La cronologia delle modifiche dell'agente logga ogni modifica con timestamp, descrizione del task e identità dell'agente. Crea una traccia di audit che finora mancava negli strumenti AI. Finalmente puoi vedere esattamente cosa hanno cambiato i tuoi agenti — e quando.

La ricerca semantica significa che puoi trovare file per concetto invece che per parola chiave. Cerca "elaborazione pagamenti" e Mycelium trova i file giusti anche se nessuno contiene la parola "pagamento." È davvero comodo per codebase più grandi dove la terminologia è cambiata nel tempo.

Privacy su cui contare

Un dettaglio importante per chi lavora in azienda: Mycelium gira in locale sulla tua macchina a localhost:47821. Il tuo codice non esce mai dal tuo ambiente di sviluppo. Non è un servizio cloud che analizza la tua logica proprietaria — è uno strumento locale che sta semplicemente fuori dai piedi.

Vale la pena configurarlo?

Per sviluppatori singoli che lavorano su progetti piccoli, Mycelium potrebbe essere eccessivo. Se il tuo codebase sono una manciata di file che conosci a memoria, probabilmente non ti serve un dependency graph.

Ma per i team, progetti più grandi, o chiunque abbia visto il proprio assistente AI annaspare per venti minuti prima di trovare il file giusto — Mycelium è un boost di produttività reale. Il costo di setup una tantum si ripaga ogni volta che il tuo agente AI ha bisogno di capire il contesto.

La promessa è convincente: il tuo assistente AI che finalmente capisce con cosa sta lavorando. Quattro file. Zero tentativi. Codice che si adatta davvero alla tua architettura.

Se sei frustrato da agenti AI che sembrano intelligenti ma non capiscono il punto, Mycelium potrebbe essere la mappa che aspettavi.