Graphify Claude Code: cos'è, come installarlo e se serve

Graphify per Claude Code è una skill open source che trasforma il tuo progetto in un grafo della conoscenza: scrivi /graphify . e Claude ottiene una mappa di file, funzioni, classi e documenti da interrogare invece di leggere i file uno per uno.

Il codice viene analizzato in locale, senza modelli AI e senza costi. Si installa con due comandi, ma conviene davvero solo su codebase medio grandi.

In questa guida a Graphify Claude Code ti spiego cos'è, come installarlo su Claude Code senza cadere nei pacchetti falsi, come costringere Claude a usarlo davvero e quando invece è solo un orpello in più.

Graphify Claude Code: cos'è e cosa fa

Graphify è un progetto open source (licenza Apache 2.0 e MIT) pubblicato su GitHub dall'organizzazione Graphify-Labs. A inizio novembre 2026 il repository supera le 140 mila stelle ed è tra i più seguiti nel mondo delle skill per agenti AI.

L'idea è semplice. Quando chiedi a Claude Code "dove si collega l'autenticazione al database?", lui di solito cerca con grep, apre file, segue gli import. Su un progetto grande questo costa token e tempo, e a volte sbaglia strada.

Graphify costruisce prima una mappa strutturale del repository e la lascia su disco, così l'agente fa una domanda precisa al grafo invece di esplorare tutto da capo.

Cosa finisce nel grafo

• Codice: circa 40 linguaggi analizzati con tree-sitter (AST). Chiamate, import ed ereditarietà vengono risolti anche tra file diversi.
• Documentazione: Markdown, PDF, immagini e, con gli extra, file Office, schemi SQL e video.
• Commenti di motivazione: i commenti tipo # WHY: o # NOTE: e i riferimenti ad ADR diventano nodi collegati al codice.
• Comunità: il grafo viene diviso in sottosistemi (algoritmo Leiden), utile per capire "chi parla con chi".

Ogni collegamento ha un'etichetta: EXTRACTED se è scritto esplicitamente nel sorgente, INFERRED se l'ha dedotto Graphify. Non è un database vettoriale: niente embedding, è un grafo vero che si attraversa.

I tre file che ottieni

Dopo il primo comando trovi una cartella graphify-out/ con:

• graph.html: la mappa interattiva da aprire nel browser, con nodi cliccabili, filtri e ricerca.
• GRAPH_REPORT.md: il riassunto con i concetti chiave (i "god node", i nodi più collegati), le connessioni sorprendenti e le domande suggerite.
• graph.json: il grafo completo, che Claude interroga senza rileggere i file.

Graphify è gratis?

Sì, la versione open source è gratuita. La parte sul codice gira tutta in locale e non consuma crediti di nessun modello. Paghi qualcosa solo in modo indiretto: documenti, PDF e immagini vengono passati al modello della tua sessione di Claude Code per l'estrazione semantica, quindi consumano il tuo abbonamento o la tua API key.

Esiste anche Graphify Cloud, un servizio a pagamento che tiene il grafo sempre aggiornato su più repository e monorepo, con connettori verso strumenti di ticketing e monitoraggio.

Offre una prova gratuita di 14 giorni; il prezzo pieno non è pubblicato nel repository, quindi non lo riporto. Per un freelance o una piccola squadra la versione gratuita basta e avanza.

Se il tuo problema principale sono i limiti di utilizzo, prima di aggiungere strumenti ti consiglio di leggere come ridurre i token in Claude Code con i comandi nativi: spesso il risparmio più grosso arriva da lì.

Come installare Graphify su Claude Code

Servono Python 3.10 o superiore e uv (oppure pipx). Se non hai ancora Claude Code, parti dalla mia guida all'installazione di Claude Code su Windows, Mac e Linux.

Attenzione al nome del pacchetto

Il pacchetto ufficiale su PyPI si chiama graphifyy, con due y. Il comando resta graphify. Gli altri pacchetti "graphify" su PyPI non sono collegati al progetto, e anche in SERP compaiono fork e copie.

È lo scenario perfetto per il typosquatting: un agente o una persona che scrive il nome sbagliato installa codice di altri. Ne ho parlato nell'articolo su HalluSquatting e agenti AI.

Installare Graphify Claude Code: i comandi passo per passo

1. Installa la CLI: uv tool install graphifyy (in alternativa pipx install graphifyy).
2. Registra la skill: graphify install. Rileva da solo Claude Code, anche su Windows.
3. Apri Claude Code nella cartella del progetto e scrivi /graphify .
4. Apri graphify-out/graph.html nel browser e leggi GRAPH_REPORT.md.
5. Collega il grafo all'agente con graphify claude install, così Claude lo consulta prima di cercare nei file.

Se vuoi la skill solo in un repository e non nel tuo profilo utente, usa graphify install --project: i file finiscono in .claude/skills/graphify/ e si possono committare per tutto il team.

Errori comuni

• "graphify: command not found": dopo l'installazione con uv esegui uv tool update-shell e riapri il terminale.
• PDF o file Office ignorati: servono gli extra, per esempio uv tool install "graphifyy[pdf]" oppure "graphifyy[office]".
• Troppe richieste di permesso: nell'app desktop molti passaggi della pipeline chiedono conferma. È un limite noto discusso dagli utenti del progetto: configura i permessi di Claude Code per i comandi graphify invece di approvare tutto alla cieca.
• Uso con Codex: il comando diventa $graphify e serve multi_agent = true nella sezione [features] di ~/.codex/config.toml.

I comandi utili dopo il primo grafo

Una volta costruito il grafo, il lavoro vero si fa con tre comandi, sia da Claude sia dal terminale:

• graphify query "domanda": restituisce solo la porzione di grafo pertinente, per esempio "cosa collega l'auth al database?".
• graphify path A B: il percorso più corto tra due elementi, con la confidenza del collegamento più debole.
• graphify explain "Nome": tutte le connessioni di un concetto, con file e riga di origine.

Per tenere il grafo fresco ci sono /graphify . --update, che rielabora solo i file cambiati, e graphify hook install, che lo ricostruisce a ogni commit e cambio di branch.

Dopo un git pull lancia graphify update .. Senza questo passaggio il grafo invecchia e l'agente lavora su una mappa sbagliata.

Perché Claude Code ignora Graphify (e come risolvere)

È la lamentela più frequente su Graphify Claude Code nelle discussioni del progetto: installi tutto, ma Claude continua a usare grep e Read come prima.

Due recensioni indipendenti in inglese arrivano alla stessa conclusione: su attività ben delimitate Claude salta il grafo perché sa già quali file aprire.

Le leve a disposizione sono tre:

• graphify claude install: scrive le istruzioni nel file di progetto e aggiunge un hook PreToolUse che, prima delle ricerche e delle letture file, spinge Claude verso il grafo.
• Modalità strict: graphify install --project --strict nega una lettura o una ricerca per sessione se l'agente non ha prima interrogato il grafo negli ultimi 30 minuti (valore predefinito). Le ricerche via Bash e Glob restano solo consigliate.
• Prompt espliciti: per le domande di architettura chiedi tu "usa graphify query per...". Funziona meglio di qualsiasi regola generica.

Il mio consiglio è di non attivare subito la modalità strict. Prima verifica che GRAPH_REPORT.md abbia contenuti sensati: se il report è povero, forzare Claude a leggerlo peggiora il lavoro invece di migliorarlo. Le regole su come delegare bene a Claude le trovi nelle best practice di Claude Code.

Privacy: cosa esce dal tuo computer

Per chi usa Graphify Claude Code su codice di clienti questa è la parte più importante:

• Codice sorgente: analizzato in locale con tree-sitter, non lascia la macchina. Un progetto di solo codice si indicizza anche offline, senza API key.
• Audio e video: trascritti in locale.
• Documenti, PDF e immagini: vanno al modello della sessione o al provider configurato. Con --code-only o GRAPHIFY_BACKEND=none li escludi; con Ollama resti tutto in locale.
• Telemetria: il progetto dichiara zero telemetria e zero analytics.
• Log delle query: ogni domanda al grafo viene salvata in ~/.cache/graphify-queries.log. Si disattiva con GRAPHIFY_QUERY_LOG_DISABLE=1.

Attenzione all'auto rilevamento del provider: se nel terminale hai una API key impostata (Gemini, Claude, OpenAI e altre), Graphify la usa in automatico per la parte semantica.

Su repository con dati personali o contratti, in ottica GDPR, imposta il backend in modo esplicito e decidi tu cosa esce. Se vuoi isolare del tutto l'agente, valuta anche un Docker Sandbox per Claude Code.

Graphify vale davvero la pena?

Dipende dalla dimensione e dalla forma del progetto. Graphify ha senso quando:

• il repository è grande o è un monorepo, e la ricerca "a tappeto" diventa costosa;
• devi orientarti in un progetto non tuo, per esempio un gestionale ereditato da un altro sviluppatore;
• fai onboarding di un collega o una revisione dell'architettura;
• codice e documentazione vivono insieme (specifiche, PDF, schemi SQL) e vuoi un'unica mappa.

Ha poco senso, invece, su un sito vetrina, una piccola web app o un task già circoscritto: Claude arriva ai file giusti più in fretta da solo, e il grafo aggiunge solo passaggi e manutenzione.

Il criterio che uso io prima di aggiungere qualsiasi skill è lo stesso che spiego nella guida alle migliori skill per Claude Code: la installo solo se risolve un problema che ho misurato, non perché è di tendenza.

Il test per Graphify Claude Code è facile: costruisci il grafo, apri il report e chiediti se ti dice qualcosa che non sapevi sul progetto.

Graphify, MCP e alternative

Graphify può funzionare anche come server MCP (extra graphifyy[mcp]), utile se vuoi esporre il grafo a più client.

Attenzione però: graphify install e la connessione MCP sono due integrazioni diverse con istruzioni diverse. Scegline una come strada principale. Se il protocollo ti è nuovo, qui spiego cos'è MCP e come funziona.

La stessa skill gira su oltre 20 assistenti: Codex, Cursor, Gemini CLI, GitHub Copilot, OpenCode, Antigravity e altri. Se stai ancora scegliendo l'agente, guarda il confronto Codex vs Claude Code.

Prima di tutto questo, però, un buon file CLAUDE.md con l'architettura descritta in poche righe resta la soluzione più economica.

Quando chiedere aiuto

Se lavori su un gestionale o un e-commerce cresciuto negli anni e vuoi usare agenti AI senza perdere il controllo su costi e dati, il punto non è aggiungere strumenti ma impostare bene il flusso. È il lavoro che faccio con le automazioni e gli agenti AI per aziende: parto dal codice reale e decido cosa serve davvero.

Hai un repository dove Claude Code si perde? Scrivimi e lo guardiamo insieme.