Ciao a tutti,
nell’articolo di oggi voglio parlarvi di Graphify, un tool open source che sto utilizzando in un progetto enterprise Angular. Questo strumento permette di creare un knowledge graph interrogabile, con l’obiettivo di abbattere il numero di token utilizzati: normalmente quando Claude (o altri agenti AI) cercando un file o una parola agiscono utilizzando il comando grep. Maggiore è la dimensione del progetto e maggiore sarà il consumo di token, mentre con questo approccio l’IA può interrogare direttamente il grafo e arrivare dritto alla risposta.
Inoltre mi sono reso conto che la qualità delle risposte ottenute era migliorata di molto e questo è ciò che più mi ha convinto a mantenerlo nel progetto.
In questo articolo vi condivido la mia esperienza dall’installazione a sul suo utilizzo.
Cosa è Graphify
Graphify è un tool esterno scritto in python che permette di mappare l’intero progetto in un grafo. L’estrazione del codice avviene in locale via tree-sitter, senza chiamate API, per documenti e media usa invece il modello della vostra IA del cuore (nel mio caso Claude). L’output finisce nella cartella graphify-out/:
graphify-out/
├── graph.html # grafo navigabile nel browser: nodi, filtri, ricerca
├── GRAPH_REPORT.md # il riassunto: concetti chiave, connessioni, domande suggerite
└── graph.json # il grafo completo, interrogabile senza rileggere i fileIl report evidenzia i god node (i concetti più connessi del progetto), le connessioni inaspettate tra moduli e marca ogni relazione inferita come EXTRACTED, INFERRED o AMBIGUOUS, in modo tale da sapere sempre cosa è stato trovato e cosa è stato dedotto.
Installazione
Come anticipato poco fa, Graphify è un tool scritto in Python e dovremo installare Python 3.10+ e un gestore di pacchetti isolato. Io ho utilizzato uv (in alternativa va bene pipx). Se non avete uv, si installa con il seguente comando:
# macOS (Homebrew)
brew install python@3.12 uv
# Windows
winget install astral-sh.uv
# Linux
curl -LsSf https://astral.sh/uv/install.sh | shVerificate con python --version e uv --version e siete pronti.
Installazione Graphify
Il pacchetto PyPI si chiama graphifyy, con la doppia y (gli altri pacchetti graphify* su PyPI non sono affiliati al progetto). Il comando CLI resta graphify.
# Consigliato: uv mette graphify nel PATH automaticamente
uv tool install graphifyy
# Alternativa
pipx install graphifyyIl pip install liscio è sconsigliato dagli stessi autori: se la skill risolve un interprete Python diverso da quello dove pip ha installato il pacchetto, vi ritroverete con un ModuleNotFoundError. Con uv tool o pipx il pacchetto vivrà in un ambiente isolato e il problema non si porrà.
Utilizzo con Claude Code
⚠️ Attenzione, non è necessario possedere un account da un provider IA (Claude, ChatGPT, ecc), questo strumento permette di costruire il grafo anche senza AI
Dopo il passaggio precedente chiudiamo e riapriamo il terminale, successivamente eseguiamo questo comando per installare graphify a livello globale e successivamente per installare la skill sul nostro progetto.
graphify install
graphify install --projectCreazione del grafo
La prima volta il grafo andrà creato: è la parte più lunga e varia a seconda della complessità del progetto. Tramite il comando qui sotto verrà creata la prima mappatura tramite AST (parsing strutturale quindi simboli, funzioni, classi, import, ecc) e semantica (gestito da Claude, se possedete un abbonamento o avete una chiave API).
Nel mio progetto ho una directory /docs dove vado a scrivere la documentazione del progetto, grazie alla skill e all’utilizzo di Claude anche il contenuto di questi file verrà mappato ed entrerà a far parte del grafo.
⚠️ Attenzione: prima di procedere è bene pensare se tutte le vostre directory siano necessarie. Nel mio caso ho dovuto escludere una directory con un progetto di documentazione caricato come git submodule perchè avrebbe solamente aggiunto “rumore” inutile ai fini di sviluppo. Per escludere delle directory potete creare un file .graphifyignore nella root del progetto con la lista delle directory.
Apriamo la CLI di Claude Code (nel progetto che vogliamo mappare) e lanciamo graphify tramite la skill
/graphify .Se non avete a disposizione un abbonamento a Claude o di altri provider potete lanciare questo comando da terminale, che si occuperà di costruire il grafo solamente tramite AST:
graphify update .Questo è il risultato del grafo generato sul progetto (monorepo nx in fase di sviluppo di un’applicazione enterprise) utilizzando la skill:
Questo invece è lo stesso grafo ma generato partendo dal comando da terminale, senza Claude:
Sulla destra è possibile visualizzare i nomi dei nodi: nella mappatura gestita da Claude i nomi sono molto più parlanti (e semanticamente corretti), mentre nel secondo esempio sono molto più generici.
Proviamo ora a lanciare un prompt e vedere se il consumo è realmente diminuito.
Test di utilizzo
Primo prompt con graphify:
Esito:
Risposta più completa e meglio strutturata a fronte di una minor numero di token utilizzati
Prompt SENZA graphify (su nuova sessione ovviamente)
Esito:
Risposta completa ma con molte meno informazioni rispetto al prompt precedente.
Graphify come default
Ora che abbiamo creato il grafo dobbiamo istruire Claude di utilizzarlo come metodo primario rispetto al comando di Grep. Per farlo basterà andare nel file CLAUDE.md ed impostare questo paragrafo:
## graphify
This project has a knowledge graph at graphify-out/ with god nodes, community structure, and cross-file relationships.
Rules:
- For codebase questions, first run `graphify query "<question>"` when graphify-out/graph.json exists. Use `graphify path "<A>" "<B>"` for relationships and `graphify explain "<concept>"` for focused concepts. These return a scoped subgraph, usually much smaller than GRAPH_REPORT.md or raw grep output.
- If graphify-out/wiki/index.md exists, use it for broad navigation instead of raw source browsing.
- Read graphify-out/GRAPH_REPORT.md only for broad architecture review or when query/path/explain do not surface enough context.
- After modifying code, run `graphify update .` to keep the graph current (AST-only, no API cost).Oltre a questo è bene installarlo anche come hook a seguito di ogni commit. Per farlo basterà digitare:
graphify hook installDue limitazioni da tenere presenti:
- Aggiorna solo i file di codice modificati nel commit, le modifiche a docs/ o immagini richiedono comunque un
/graphify --update .manuale - Gira in post-commit, quindi il commit non viene bloccato se fallisce
Conclusioni
In questi tempi incerti dove l’accesso all’hardware è sempre più per pochi, risparmiare token e ottimizzare i consumi dei nostri abbonamenti diventa di vitale importanza. Non basta questo strumento per risolvere qualunque problema di ottimizzazione, ma graphify è un qualcosa che utilizzo insieme ad altri strumenti (es. caveman, per citarne uno) e la sensazione è che, oltre ad ottimizzare i token, anche la qualità delle risposte è aumenta, che è ciò che più mi ha convinto. Provare per credere!😊
Grazie per aver letto, alla prossima!
