# graphify - **Autore:** Graphify Labs - **Repository:** [Graphify-Labs/graphify](https://github.com/Graphify-Labs/graphify) (licenza Apache-2.0; branch principale `v8`) - **Sorgente:** [graphify/skill.md](https://github.com/Graphify-Labs/graphify/blob/v8/graphify/skill.md) (versione per Claude Code; le versioni per gli altri agenti sono in `graphify/skill-.md`, le guide di dettaglio in `graphify/skills//references/`) - **Pacchetto Python:** `graphifyy` (con due y); il comando si chiama `graphify` - **Pagina su skills.sh:** [graphify-labs/graphify/graphify](https://skills.sh/graphify-labs/graphify/graphify) - **Versione:** v0.9.91 (14 ottobre 2026) - **Diffusione (ottobre 2026):** circa 9.700 installazioni tramite `npx skills` (su skills.sh dal 7 aprile 2026); il repository ha circa 127.000 stelle e 12.300 fork su GitHub. La maggior parte degli utenti installa tramite il pacchetto Python, che skills.sh non conta. - **Controlli di sicurezza su skills.sh:** Gen Agent Trust Hub, Socket e Snyk superati (a settembre Socket segnalava un avviso) > Esistono siti di terzi con nomi simili. Questa scheda si basa solo sul repository ufficiale Graphify-Labs/graphify. ## A cosa serve Trasforma una cartella (codice, documentazione, PDF, immagini, video) in un **grafo di conoscenza** interrogabile: nodi come classi, funzioni e concetti, collegati da relazioni come chiamate, import ed ereditarietà. Invece di cercare nei file con grep e rileggerli ogni volta, l'agente interroga il grafo, e così spende meno token sui progetti grandi e vede collegamenti tra parti lontane del progetto. ## Cosa fa ### Quando si attiva Con il comando `/graphify`, oppure per qualsiasi domanda su un progetto (architettura, relazioni tra file, contenuti), soprattutto se la cartella `graphify-out/` esiste già. In quel caso l'agente risponde interrogando il grafo invece di ricostruirlo. ### Come lavora 1. **Controlla l'installazione:** se il pacchetto `graphifyy` manca, l'agente lo installa da solo con `uv tool install`, oppure con `pip` (se necessario anche con `--break-system-packages`). 2. **Conta i file** e ne mostra il riepilogo per tipo (codice, documenti, articoli, immagini, video). Segnala i file saltati perché ritenuti sensibili. Sopra i 500 file o i 2 milioni di parole avvisa e chiede su quale sottocartella lavorare. 3. **Estrae entità e relazioni** in due parti parallele: - **codice:** analisi sintattica locale con tree-sitter, deterministica e gratuita, senza modelli linguistici e senza chiavi API; - **documenti, PDF e immagini:** estrazione del significato con un modello linguistico. Se è impostata `GEMINI_API_KEY` o `GOOGLE_API_KEY` usa Gemini; altrimenti lo fa l'agente stesso (in Claude Code con dei subagenti), consumando token della sessione. La skill dice esplicitamente di non chiedere mai altre chiavi API. - Audio e video vengono prima trascritti in locale con Whisper. 4. **Costruisce il grafo**, raggruppa i nodi in comunità (algoritmo di Leiden) e ne controlla l'integrità. 5. **Dà un nome alle comunità** e genera i risultati. 6. **Riassume in chat** i nodi più collegati, i collegamenti inattesi e le domande suggerite, poi propone la domanda più interessante da esplorare insieme. Ogni relazione è etichettata `EXTRACTED` (scritta nel sorgente), `INFERRED` (dedotta) o `AMBIGUOUS` (incerta). Le regole di onestà della skill vietano di inventare relazioni, e impongono di mostrare sempre il costo in token e di avvisare prima di visualizzare grafi con più di 5.000 nodi. ### Risultati Nella cartella `graphify-out/`: | File | Contenuto | |---|---| | `graph.html` | mappa interattiva del grafo, con filtri e ricerca | | `GRAPH_REPORT.md` | rapporto leggibile: nodi più collegati, collegamenti inattesi, motivazioni trovate nei commenti (`# WHY:`, `# NOTE:`), domande suggerite | | `graph.json` | il grafo completo, per interrogarlo | A richiesta produce anche SVG, GraphML (Gephi, yEd), script per Neo4j o FalkorDB, una wiki Markdown e un vault di Obsidian. ### Comandi principali ``` /graphify # grafo della cartella corrente /graphify # grafo di una cartella /graphify https://github.com// # clona il repository e ne fa il grafo /graphify --update # rielabora solo i file nuovi o modificati /graphify --mode deep # estrazione più approfondita /graphify --watch # ricostruisce il grafo quando il codice cambia /graphify --obsidian # esporta anche un vault di Obsidian /graphify --wiki # wiki Markdown, un articolo per comunità /graphify --mcp # avvia un server MCP sul grafo /graphify query "" # risponde usando il grafo /graphify path "ModuloA" "ModuloB" # percorso più breve tra due concetti /graphify explain "NomeFunzione" # spiega un nodo /graphify add # aggiunge una pagina web al corpus ``` Da terminale, fuori dall'agente: ```bash graphify update ./src # aggiorna il grafo dopo un git pull graphify hook install # ricostruisce il grafo a ogni commit graphify extract ./src --code-only # solo codice, nessuna chiamata esterna ``` ### Supporto - **Codice:** circa 40 linguaggi, tra cui Python, TypeScript, JavaScript, Go, Rust, Java, C/C++, C#, Ruby, PHP, Swift e Kotlin, più Terraform e i file di configurazione dei pacchetti. - **Documenti:** Markdown, reStructuredText, HTML, YAML, testo, PDF, DOCX e XLSX. - **Media:** immagini, audio e video, e anche URL di YouTube (richiede l'extra `video`). ### Da sapere - **Requisiti:** Python 3.10 o successivo; `uv` consigliato (va bene anche `pipx` o `pip`). - **Privacy:** l'analisi del codice è interamente locale. Documenti, PDF e immagini passano dal modello linguistico usato: Gemini, se hai impostato la chiave, oppure l'agente stesso. Il README dichiara che non c'è telemetria. Il registro delle interrogazioni è facoltativo e locale (`~/.cache/graphify-queries.log`); si disattiva con `GRAPHIFY_QUERY_LOG_DISABLE=1`. - **Chiavi API:** dentro l'agente la skill usa solo Gemini o l'agente stesso. Il comando da terminale `graphify extract --backend `, pensato per l'automazione, secondo il README supporta anche Anthropic, OpenAI, DeepSeek, Kimi, Bedrock e Ollama in locale. - **Costi:** un corpus di solo codice non costa token per la costruzione. Con documenti e immagini senza chiave Gemini, l'estrazione consuma token della sessione dell'agente. - **Modifiche al sistema e al progetto:** la skill installa pacchetti Python da sola e crea `graphify-out/` nel progetto. L'integrazione "sempre attiva" modifica `CLAUDE.md` o `AGENTS.md` e aggiunge hook che spingono l'agente a interrogare il grafo prima di leggere o cercare nei file (vedi sotto). - **File nel progetto:** se la cartella è dentro un repository git, la skill avvisa che `graphify-out/` compare in `git status`, a meno che sia già ignorata. - **Graphify Cloud:** il README promuove anche un servizio a pagamento con prova gratuita di 14 giorni (grafo sempre aggiornato su più repository, collegamenti con Sentry e Jira). Non serve per usare la skill, che resta locale. - **Grafo da aggiornare:** il grafo è una fotografia del codice. Va aggiornato con `--update`, `graphify update`, `--watch` o l'hook sui commit. ## Installazione ### Claude Code (metodo ufficiale) ```bash uv tool install graphifyy # oppure: pipx install graphifyy / pip install graphifyy graphify install # installa la skill in ~/.claude/skills/graphify/ ``` Con `graphify install --project` la installa solo nel progetto corrente (`.claude/skills/`). Poi in Claude Code, dalla cartella del progetto: ``` /graphify . ``` **Integrazione sempre attiva** (facoltativa, dopo aver costruito il grafo): aggiunge una sezione a `CLAUDE.md` e un hook `PreToolUse` che, prima di ogni lettura o ricerca nei file, invita Claude a usare il grafo. ```bash graphify claude install graphify install --project --strict # variante rigida: blocca la prima lettura diretta dei file ``` La modalità rigida si attiva o disattiva al momento con `GRAPHIFY_HOOK_STRICT=1` o `GRAPHIFY_HOOK_STRICT=0`. ### Codex ```bash uv tool install graphifyy graphify install --platform codex graphify codex install # integrazione sempre attiva tramite AGENTS.md ``` Per Codex l'installazione scrive le istruzioni in `AGENTS.md` e un hook in `.codex/hooks.json`, che secondo il README di proposito non fa niente, perché Codex rifiuta alcuni output degli hook. Altre piattaforme: `graphify cursor install`, `graphify install --platform gemini`, `--platform copilot`, `--platform aider`, `--platform agents` (formato Agent Skills, in `~/.agents/skills/graphify/`). ### Con `npx skills` ```bash npx skills add Graphify-Labs/graphify --skill graphify -g -a claude-code -a codex ``` Installa solo le istruzioni della skill. Il pacchetto Python viene installato dall'agente al primo `/graphify`, ma l'integrazione sempre attiva e gli hook no: per quelli serve comunque il comando `graphify`. Il metodo documentato nel README è quello con `uv tool install` + `graphify install`. ### Estensioni facoltative ```bash uv tool install "graphifyy[pdf]" # PDF uv tool install "graphifyy[video]" # audio e video (trascrizione locale) uv tool install "graphifyy[neo4j]" # esportazione verso Neo4j uv tool install "graphifyy[all]" # tutto ``` ### Aggiornamento e rimozione ```bash uv tool upgrade graphifyy && graphify install # aggiorna pacchetto e skill graphify hook uninstall # rimuove l'hook sui commit graphify uninstall # rimuove la skill da tutte le piattaforme graphify uninstall --project # solo i file del progetto graphify uninstall --purge # rimuove anche graphify-out/ ``` ### App desktop di Claude e ChatGPT Il README non prevede l'uso nelle app di chat. La skill ha bisogno di installare un pacchetto Python, eseguire comandi nel terminale e leggere una cartella di progetto sul tuo computer, quindi nell'ambiente isolato delle app probabilmente non è utilizzabile. Non l'ho verificato. ## Fonti - [README di Graphify-Labs/graphify](https://github.com/Graphify-Labs/graphify) - [graphify/skill.md](https://github.com/Graphify-Labs/graphify/blob/v8/graphify/skill.md) - [Release del repository](https://github.com/Graphify-Labs/graphify/releases) - [graphify su skills.sh](https://skills.sh/graphify-labs/graphify/graphify) - [README di vercel-labs/skills](https://github.com/vercel-labs/skills)