README.it IT

Riduci dell'80% la spesa in token dei tuoi agenti. Graphify Cloud è una memoria sempre attiva che governa i tuoi agenti, mantiene alta la qualità del codice e dimostra la correttezza con la verifica formale. Inizia una prova gratuita di 14 giorni →

Digita /graphify nel tuo assistente di programmazione con IA e mappa l'intero progetto (codice, documenti, PDF, immagini, video) in un grafo della conoscenza che puoi interrogare invece di fare grep tra i file.

• Mappatura del codice gratuita, interamente locale. Il codice viene analizzato con l'AST di tree-sitter: deterministico, senza LLM, nulla lascia la tua macchina. (Documenti, PDF, immagini e video usano il modello del tuo assistente, o una chiave API configurata, per una passata semantica.)
• Ogni arco è spiegato. Ogni connessione è etichettata come EXTRACTED (esplicita nella fonte) o INFERRED (risolta da graphify), così puoi distinguere ciò che è stato letto direttamente da ciò che è stato inferito.
• Non è un indice vettoriale. Niente embedding, niente archivio di vettori: un vero grafo che percorri. Fai una domanda, traccia il percorso tra due cose o spiega un concetto.

[!NOTE] Lo vuoi sempre attivo? Graphify Cloud mantiene il grafo vivo lungo tutto il tuo SDLC: supporto per monorepo e multi-repository, verifica formale e revisione del codice con una visione d'insieme del tuo SDLC, più connettori per Sentry, Jira e altro, così che incidenti e ticket si trovino nello stesso grafo del tuo codice. Inizia una prova gratuita di 14 giorni su app.graphify.com.

La base di codice di FastAPI mappata da graphify. Ogni nodo è un concetto, i colori sono comunità rilevate e il tutto è cliccabile in graph.html.

Per iniziare (30 secondi). Richiede Python 3.10+ e uv (o pipx):

uv tool install graphifyy      # install the CLI (or: pipx install graphifyy)
graphify install               # detects your assistant and registers the skill

Poi, nel tuo assistente IA:

/graphify .

Ecco fatto. Ottieni tre file:

graphify-out/
├── graph.html       open in any browser: click nodes, filter, search
├── GRAPH_REPORT.md  the highlights: key concepts, surprising connections, suggested questions
└── graph.json       the full graph: query it anytime without re-reading your files

Il grafo persistito include graph.schema_version così che le integrazioni possano rilevare modifiche di formato incompatibili, più graph.graphify_version che identifica la versione di Graphify che lo ha prodotto.

Un'unica installazione, qualsiasi assistente, qualsiasi OS. Claude Code, Cursor, Codex, Gemini CLI, GitHub Copilot e oltre 20 altri, su macOS, Linux e Windows: scegli la tua piattaforma.

See it in action¶

Una volta costruito il grafo, lo interroghi invece di leggere i file. Output reale, graphify eseguito sulla base di codice di FastAPI mostrata sopra:

$ graphify explain "APIRouter"
Node: APIRouter
  Source:    routing.py L2210
  Community: 2
  Degree:    47

Connections (47):
  --> RequestValidationError [uses] [INFERRED]
  --> Dependant [uses] [INFERRED]
  --> .get() [method] [EXTRACTED]
  <-- __init__.py [imports] [EXTRACTED]
  ...

$ graphify path "FastAPI" "ModelField"
Shortest path (3 hops):
  FastAPI --uses--> DefaultPlaceholder <--references-- get_request_handler() --references--> ModelField

Ogni arco porta un tag di confidenza (EXTRACTED = esplicito nella fonte, INFERRED = derivato dalla risoluzione), così puoi distinguere ciò che è stato letto direttamente da ciò che è stato inferito. graphify query "<question>" restituisce un sottografo mirato per una domanda in linguaggio naturale, e graphify path A B traccia come due cose qualsiasi sono collegate.

What it does¶

Ciò che ottieni da subito:

[!TIP] Lo esegui su molti repository o su un monorepo? Graphify Cloud lo fa di continuo e riduce la spesa in token degli agenti dell'80%, con collegamenti multi-repository, revisione del codice su scala SDLC, verifica formale e connettori Sentry/Jira. Inizia una prova gratuita di 14 giorni →

Benchmarks: 0.497 recall@10, 0 LLM credits¶

Ogni sistema è stato eseguito sullo stesso harness con lo stesso modello e gli stessi budget, valutato da un giudice validato alla cieca contro un secondo giudice (90,6% di accordo, kappa di Cohen 0,81). Le tabelle complete per sistema, il risultato di code-intelligence e i comandi di riproduzione: BENCHMARKS.md.

Documentation¶

Guide complete e riferimento disponibili su docs.graphify.com:

• Quickstart: costruisci il tuo primo grafo
• CLI reference: ogni comando e flag
• Ask better graph questions: schemi di interrogazione
• Configuration: variabili d'ambiente e regolazioni
• Supported inputs: linguaggi e tipi di file
• Team workflows e PR review
• Troubleshooting e How it works

Prerequisites¶

Installazione rapida su macOS (Homebrew):

brew install python@3.12 uv

Installazione rapida su Windows:

winget install astral-sh.uv

Ubuntu/Debian:

sudo apt install python3.12 python3-pip pipx
# or install uv:
curl -LsSf https://astral.sh/uv/install.sh | sh

Install¶

[!IMPORTANT] Pacchetto ufficiale: il pacchetto PyPI è graphifyy (doppia y). Altri pacchetti graphify* su PyPI non sono affiliati. Il comando CLI resta graphify.

Il repository sorgente ufficiale è Graphify-Labs/graphify.

Il quickstart a due comandi è in cima a questo README. Questa sezione copre i metodi di installazione, le installazioni con ambito di progetto e ogni piattaforma supportata.

Metodi di installazione (scegline uno):

uv tool install graphifyy   # recommended, isolated env (if 'graphify' isn't found after, run: uv tool update-shell)
pipx install graphifyy      # alternative
pip install graphifyy       # may need PATH setup, see Troubleshooting below

Poi esegui graphify install una volta. Rileva quale assistente usi e registra la skill, così non c'è alcuna configurazione per singolo assistente. Apri il tuo assistente IA e digita /graphify .

Per installare la skill dell'assistente nel repository corrente anziché nel tuo profilo utente, aggiungi --project:

graphify install --project
graphify install --project --platform codex

Le installazioni con ambito di progetto scrivono sotto la directory corrente, ad esempio .claude/skills/graphify/SKILL.md o .agents/skills/graphify/SKILL.md (più un sidecar references/ che la skill carica su richiesta), e stampano un suggerimento git add per i file che possono essere committati. I comandi per piattaforma che supportano le installazioni con ambito di progetto accettano lo stesso flag, ad esempio graphify claude install --project o graphify codex install --project.

[!TIP] Ti imbatti in command not found, un problema pip su Mac/Windows, il quoting di PowerShell, l'uso di uvx, stranezze del PATH nei git-hook o la modalità strict? Vedi Installation e Troubleshooting.

Make your assistant always use the graph¶

Esegui questo una volta nel tuo progetto dopo aver costruito un grafo:

Esegui graphify <platform> install una volta nel tuo progetto, ad esempio graphify claude install o graphify codex install (oppure graphify install --platform <name>).

Questo scrive un piccolo file di configurazione che indica al tuo assistente di consultare il grafo della conoscenza per le domande sulla base di codice, preferendo query mirate come graphify query "<question>" alla lettura dell'intero report o al grep di file grezzi.

• Piattaforme con hook (Claude Code, Gemini CLI): un hook si attiva automaticamente prima delle chiamate a strumenti di tipo ricerca (e, su Claude Code, prima di leggere i file sorgente uno per uno tramite gli strumenti Read/Glob) e indirizza il tuo assistente verso il percorso del grafo.
• Piattaforme con file di istruzioni (Codex, OpenCode, Cursor, ecc.): file di istruzioni persistenti (AGENTS.md, .cursor/rules/, ecc.) forniscono la stessa guida query-first.

GRAPH_REPORT.md resta disponibile per una revisione ampia dell'architettura.

Quali file esattamente scrive ciascuna piattaforma (il CODEBUDDY.md + hook PreToolUse di CodeBuddy, l'AGENTS.md di Codex, il plugin nativo .kilo di Kilo, la regola alwaysApply di Cursor e così via) è trattato in Always-on setup.

Per rimuovere graphify da tutte le piattaforme in una volta: graphify uninstall (aggiungi --purge per eliminare anche graphify-out/). Oppure usa il comando per piattaforma (ad es. graphify claude uninstall).

CLI skills or MCP instructions?¶

Le istruzioni installate da graphify install e quelle fornite con una connessione MCP di Graphify descrivono modi diversi di interrogare un grafo:

Entrambi incoraggiano query mirate sul grafo prima di ricerche ampie nella fonte. Scegli le istruzioni che corrispondono agli strumenti a cui il tuo assistente può effettivamente accedere; nessuno dei due blocchi stabilisce una regola di precedenza universale per i file di istruzioni del tuo assistente. Se usi entrambe le integrazioni, individua quale grafo interroga ciascuna e scegli un percorso di query primario invece di copiare due blocchi di istruzioni incondizionati in AGENTS.md.

graphify install installa l'integrazione locale dell'assistente; non stabilisce una connessione MCP. Un client MCP non ha bisogno di eseguire query CLI locali per usare il suo server connesso. Un server ospitato localmente ha comunque bisogno della propria installazione di Graphify e del proprio grafo, mentre una connessione ospitata può servire un grafo che non è presente nella directory di lavoro del client. Se gli strumenti attesi mancano, controlla la relativa installazione CLI o connessione MCP invece di trattare le istruzioni dell'altra configurazione come intercambiabili.

What's in the report¶

GRAPH_REPORT.md riassume i god nodes, le comunità e i percorsi chiave per una revisione ampia dell'architettura. Come viene costruito il grafo e cosa contiene: How graphify works.

What files it handles: ~40 languages¶

graphify analizza ~40 linguaggi di programmazione localmente con l'AST di tree-sitter, e mappa documenti, PDF, immagini e audio/video tramite una passata semantica opzionale. Elenco completo: Supported inputs.

Common commands¶

/graphify .                        # build graph for current folder
/graphify ./docs --update          # re-extract only changed files
/graphify . --cluster-only         # rerun clustering without re-extracting
/graphify . --cluster-only --resolution 1.5      # more granular communities
/graphify . --cluster-only --exclude-hubs 99     # suppress utility super-hubs from god-node rankings
/graphify . --no-viz               # skip the HTML, just the report + JSON
/graphify . --wiki                 # build a markdown wiki from the graph
graphify export callflow-html      # Mermaid architecture/call-flow HTML (auto-regenerates on every git commit if hook is installed)

/graphify query "what connects auth to the database?"
/graphify path "UserService" "DatabasePool"
/graphify explain "RateLimiter"

/graphify add https://arxiv.org/abs/1706.03762   # fetch a paper and add it
/graphify add <youtube-url>                       # transcribe and add a video

graphify hook install              # auto-rebuild on commit + branch checkout (run `graphify update .` after `git pull`: see "Recommended workflow" below)
graphify merge-graphs a.json b.json              # combine two graphs

graphify prs                       # PR dashboard: CI state, review status, worktree mapping
graphify prs 42                    # deep dive on PR #42 with graph impact
graphify prs --triage              # AI ranks your review queue (uses whatever backend is configured)
graphify prs --conflicts           # PRs sharing graph communities: merge-order risk

Vedi il riferimento completo dei comandi più sotto.

Ignoring files¶

graphify rispetta .gitignore e supporta i pattern --exclude e un file di progetto .graphifyignore. Dettagli: Configuration.

Project configuration¶

Crea un .graphifyrc nella radice della scansione per le impostazioni che appartengono al progetto anziché a una singola esecuzione. Un key=value per riga; le righe che iniziano con # sono commenti.

Estensioni ambigue. Alcune estensioni indicano linguaggi diversi in progetti diversi: .inc è PHP su pfSense, Pascal in un albero Delphi, SQL o assembly altrove; .h è C o C++; .m è Objective-C o MATLAB. graphify deve scegliere un unico default globale, e quando sceglie male il file non fallisce: viene analizzato come il linguaggio sbagliato e produce una manciata di nodi incidentali, così il grafo sembra popolato mentre i simboli reali mancano. Dichiara cosa significa l'estensione nel tuo repo:

# .graphifyrc
# A language name:
language.inc=php
# Or an extension graphify already knows:
language.tpl=.ts
# Baked into the git hooks (see Team setup):
viz_node_limit=0

La dichiarazione fluisce attraverso la classificazione, la selezione dell'estrattore, la grammatica e la risoluzione, le importazioni, graphify watch e la cache AST (un file rianalizzato con un linguaggio diverso non riutilizza mai la vecchia voce), e lo stesso .graphifyrc viene letto da extract, update, dagli hook, dal server MCP e dalla skill /graphify. Un errore di battitura viene segnalato una volta su stderr e la scansione continua con i default. Come le dichiarazioni interagiscono con il caching, le ricostruzioni incrementali e la risoluzione delle importazioni: Configuration.

Team setup¶

Esegui il commit o condividi il grafo in modo che tutto il tuo team interroghi lo stesso contesto, e revisiona le pull request con il contesto del grafo. Vedi Share context with your team e Review pull requests.

Using the graph directly¶

Oltre al tuo assistente IA, interroga graph.json direttamente dalla CLI con graphify query, graphify path e graphify explain. Un nome che corrisponde a più nodi viene rifiutato con l'elenco dei candidati anziché indovinato. Gli script possono leggere l'esito dal codice di uscita: 0 una risposta, 3 un nome ambiguo, 4 nessun nodo corrispondente. Vedi Ask better graph questions e il query reference.

Environment variables¶

Backend, chiavi API, comportamento degli hook e regolazioni sono controllati da variabili d'ambiente. Tabella completa: Configuration.

Privacy¶

• File di codice: elaborati localmente tramite tree-sitter. Nulla lascia la tua macchina. Un corpus di solo codice non richiede alcuna chiave API: graphify extract gira interamente offline. Su un repo misto, aggiungi --code-only per indicizzare solo il codice e saltare i documenti/PDF/immagini che altrimenti richiederebbero un LLM.
• Video / audio: trascritti localmente con faster-whisper. Nulla lascia la tua macchina.
• Documenti, PDF, immagini: inviati al tuo assistente IA per l'estrazione semantica (tramite la skill /graphify, usando qualunque modello esegua la tua sessione IDE). In modalità headless, graphify extract richiede GEMINI_API_KEY / GOOGLE_API_KEY (Gemini), MOONSHOT_API_KEY (Kimi), ANTHROPIC_API_KEY (Claude), OPENAI_API_KEY (OpenAI), DEEPSEEK_API_KEY (DeepSeek), un'istanza Ollama in esecuzione (OLLAMA_BASE_URL), credenziali AWS tramite la catena di provider standard (Bedrock: nessuna chiave API necessaria, usa IAM), o il binario CLI claude (Claude Code: nessuna chiave API necessaria, usa il tuo abbonamento Claude). Il flag --dedup-llm usa la stessa chiave.
• Residenza dei dati: graphify extract rileva automaticamente quale provider usare in base a quale chiave API è impostata (priorità: Gemini → Kimi → Claude → OpenAI → DeepSeek → Azure → Bedrock → Ollama). Per codice con requisiti di residenza dei dati, usa --backend ollama (interamente locale) o passa un flag --backend esplicito. Kimi (MOONSHOT_API_KEY) instrada ai server di Moonshot AI in Cina.
• Nessuna telemetria, nessun tracciamento dell'uso, nessuna analitica.
• Logging delle query: ogni chiamata graphify query, graphify path, graphify explain e MCP query_graph viene registrata in ~/.cache/graphify-queries.log in formato JSON Lines (timestamp, domanda, corpus, nodi restituiti, durata). Le risposte complete del sottografo non vengono memorizzate per impostazione predefinita. Imposta GRAPHIFY_QUERY_LOG_DISABLE=1 per disattivare, o GRAPHIFY_QUERY_LOG=/dev/null per silenziarlo senza disabilitare il percorso di codice.

Troubleshooting¶

Problemi comuni di installazione ed estrazione e le relative soluzioni: Troubleshooting.

Full command reference¶

Ogni comando e flag, con esempi: CLI reference.

Learn more¶

• docs.graphify.com: documentazione completa: guide, riferimento dei comandi e integrazioni
• How it works: la pipeline di estrazione, il rilevamento delle comunità, lo scoring di confidenza, i benchmark
• ARCHITECTURE.md: suddivisione dei moduli, come aggiungere un linguaggio
• Optional integrations: Docker MCP Toolkit + SQLite
• The Memory Layer: il libro sulle idee dietro graphify, l'architettura dall'inizio alla fine

Graphify Cloud¶

Graphify Cloud è lo strato sempre attivo costruito sopra graphify. Invece di un grafo che ricostruisci su richiesta per cartella, mantiene un unico grafo vivo lungo tutto il tuo ciclo di vita dello sviluppo software:

• 80% di token in meno: una memoria sempre attiva significa che i tuoi agenti smettono di rileggere e rispiegare la base di codice a ogni sessione.
• Monorepo e multi-repository: un unico grafo connesso su ogni servizio e repository, non un grafo per cartella.
• Verifica formale: controlla gli invarianti di architettura e dipendenze rispetto al grafo vivo.
• Revisione del codice con una visione d'insieme del tuo SDLC: osserva come una modifica si propaga nell'intero sistema prima di fare il merge.
• Connettori SDLC: integra Sentry, Jira e altro, così che incidenti, ticket e codice vivano in un unico grafo.
• Sempre attivo: si aggiorna di continuo in background attraverso codice, documenti e riunioni.

Inizia una prova gratuita di 14 giorni su app.graphify.com →

Contributing¶

I contributi sono benvenuti. Vedi CONTRIBUTING.md per la configurazione di sviluppo, i comandi di test e di parità con la CI, il flusso di lavoro git e cosa rende un contributo solido (gli esempi elaborati e le segnalazioni di bug di estrazione sono i più utili). Architettura e come aggiungere un linguaggio: ARCHITECTURE.md.

Nuovo qui? Saluta su Discord o nelle GitHub Discussions.

Contributors¶

Realizzato con contrib.rocks.

Translations¶

Il README è disponibile in 32 lingue. Usa il selettore di lingua in cima a questo file per leggerlo nella tua, oppure sfoglia docs/translations/. Per migliorare una traduzione o aggiungerne una nuova, apri una pull request sul file corrispondente.

Building on graphify¶

Stai costruendo qualcosa nell'ecosistema di graphify? È incoraggiato. Se il tuo progetto usa «graphify» nel nome (ad esempio graphify-dashboard o graphify-action), aggiungi una breve nota al tuo README che chiarisca che è costruito dalla comunità e non è affiliato né approvato da Graphify Labs. «graphify» e il logo di graphify sono marchi di Graphify Labs; ti preghiamo di non usarli in un modo che lasci intendere uno status ufficiale.

Community and links¶