Analisi locale del codice per 8 linguaggi e SQLite SQL.
Chiedi al tuo coding agent dove intervenire, cosa potrebbe essere coinvolto e quali test lanciare.
Installazione · Uso con il coding agent · Guida · Quando conviene · Come funziona · Ricerca ibrida · Benchmark · Dashboard · Due mappe · Modifica con un agente · CLI · MCP · Linguaggi · Limiti · Novità · Sponsor
Incolla questo messaggio nella chat di Codex o Claude Code:
Installa code-graph seguendo https://github.com/dagoSte/code-graph/blob/main/SETUP.md: mostrami prima il piano, aspetta il mio sì, poi installalo e verifica che funzioni.
Leggi il piano di installazione e approvalo. Quando la verifica è riuscita, apri una nuova sessione dell’agente nel repository su cui vuoi lavorare.
Collega un client MCP se preferisci usare code-graph tramite MCP.
Installazione manuale e aggiornamento
Requisiti: Git, Bash e Python 3.10+ con venv. Verificato su macOS arm64; la CI esegue l’intera suite su Linux e macOS con Python 3.12 e 3.13. Il flusso di modifica richiede anche codex e/o claude installati e con accesso eseguito.
git clone https://github.com/dagoSte/code-graph.git "$HOME/code-graph"
cd "$HOME/code-graph"
CG_PYTHON=python3.12 bash scripts/setup.sh
CG="$HOME/code-graph/scripts/cg"setup.sh crea .venv dentro la cartella della skill, installa le dipendenze fissate in requirements.txt (solo wheel binarie) ed esegue cg selftest. Nel Python di sistema non viene installato nulla. Se per il tuo interprete non esiste una wheel, scegline un altro con CG_PYTHON.
Collega l’intera cartella come skill (la destinazione non deve esistere):
mkdir -p "$HOME/.codex/skills" "$HOME/.claude/skills"
ln -s "$HOME/code-graph" "$HOME/.codex/skills/code-graph" # Codex
ln -s "$HOME/code-graph" "$HOME/.claude/skills/code-graph" # Claude CodeNon copiare il solo SKILL.md: la skill ha bisogno dei suoi script e del suo ambiente. Se l’agente non vede la skill, apri una nuova sessione.
Aggiornamento: git pull, poi di nuovo bash scripts/setup.sh. L’indice è una cache: un indice di una versione precedente viene ricostruito al successivo index.
Le grammatiche sono incluse nella wheel fissata di tree-sitter-language-pack, quindi l’indicizzazione funziona offline. Il launcher esegue Python con -I, così i moduli del tuo progetto o di PYTHONPATH non vengono mai importati.
Dopo la configurazione ti basta la chat del coding agent. L’agente usa code-graph tramite la skill o la connessione MCP del progetto. Prova a incollare questo esempio:
Usa code-graph per analizzare questa modifica: annullare un ordine deve
anche rimborsare i pagamenti parziali. Mostrami dove intervenire con file e
righe, cosa potrebbe essere coinvolto e quali test lanciare.
Mostrami il piano prima di modificare il codice.
L’agente può creare o aggiornare l’indice, trovare il codice pertinente, risalire ai chiamanti e proporti i test. Ricevi la risposta nella stessa chat. Funziona anche per richieste come «Usa code-graph per spiegarmi questo stack trace» o «Usa code-graph per verificare cosa ha toccato la mia modifica».
La guida per gli agenti raccoglie altri prompt e opzioni di configurazione. Puoi anche usare direttamente la dashboard o la riga di comando.
code-graph-1.9.0-overview-en.mp4
Scarica la presentazione in inglese con sottotitoli · MP4
Benchmark. Con lo stesso limite di 4.000 caratteri per risposta, il file della correzione storica è comparso fra i primi cinque candidati in 28 casi su 44 valutabili, rispetto ai 17 su 44 di partenza. Metodo e risultati dei benchmark
Gli agenti di programmazione spendono gran parte dello sforzo a trovare il codice giusto: cercano con grep, aprono i file uno a uno e indovinano cosa romperà una modifica. code-graph costruisce una volta il grafo statico del progetto, lo aggiorna in modo incrementale e risponde alle domande di cui un agente ha davvero bisogno:
- Dov’è il codice di questa richiesta? La ricerca ibrida ordina le dichiarazioni per pertinenza testuale (SQLite FTS5/BM25), poi segue chiamate e riferimenti per portare dentro le funzioni che contano ma non contengono le tue parole. → Ricerca ibrida
- Cosa si rompe se lo cambio? Chi chiama, fino alla profondità che scegli, con il punto di chiamata per ciascuno, e i test che raggiungono il simbolo.
- Cosa deve leggere esattamente l’agente? Finestre di sorgente delimitate con hash SHA-256, un budget di caratteri e l’elenco esplicito di ciò che è stato omesso.
- La modifica ha fatto ciò che diceva? Dopo la modifica firme, chiamate e segnalazioni si confrontano con una base, così un problema nuovo non si confonde con uno vecchio.
Indicizzazione e ricerca girano sul tuo computer: l’analisi non importa i tuoi moduli, non esegue il tuo codice, non chiama modelli e non invia sorgenti da nessuna parte. Ciò che il tuo agente legge poi arriva al provider di quell’agente, come in ogni sessione con un agente; vedi PRIVACY.md. Il grafo guida la lettura, non prova il comportamento: l’agente legge comunque il sorgente e decidono i tuoi test.
| 8 linguaggi + SQL | PHP, Python, JavaScript/TypeScript, Go, Dart, Java, Swift e mappe delle risorse SQLite SQL, ciascuno con un contratto di copertura scritto |
| 4 modi di usarlo | riga di comando cg, dashboard locale, server MCP (15 strumenti), skill per Claude Code e Codex |
| Scala | Il Go SDK reale (2,2 milioni di righe, 7.035 file) si indicizza in 52 s; dopo la modifica di un file si aggiorna in 9 s (misure) |
| Nessun servizio | Gratuito (FSL-1.1-MIT), nessun account, dipendenze fissate, funziona offline una volta installato |
| Usalo | Lascia perdere |
|---|---|
| Centinaia di file o più, oppure codice che non hai scritto tu | Progetti piccoli: una decina di file si leggono altrettanto in fretta |
| Una modifica di cui non sei sicuro della portata: funzioni condivise, API pubbliche | Una correzione di una riga in un file che conosci già |
| Devi sapere quali test lanciare prima e dopo | Codice guidato soprattutto da reflection, route registrate come stringhe o dependency injection, dove mancano archi statici |
| Una sessione con un agente con domande ripetute dov’è X / chi chiama Y | Domande a cui basta un grep |
Il grafo aiuta a passare da una richiesta ai riferimenti nel sorgente, a vedere chi chiama il codice e a scegliere quali test eseguire. Nel benchmark sintetico, il grafo ha trovato funzioni pertinenti sfuggite alla ricerca testuale. Risultati della ricerca ibrida
flowchart LR
P["I tuoi sorgenti<br/>analizzati da tree-sitter<br/>(incluso, offline)"] --> A["Adattatori per linguaggio<br/>dichiarazioni · chiamate<br/>riferimenti"]
A --> G["Grafo di chiamate e riferimenti<br/>confidenza statica"]
A --> F["Indice full-text FTS5<br/>nomi · firme · corpi"]
G --> Q{{"search · impact · context<br/>verify · review"}}
F --> Q
Q --> E["Evidenze per il tuo agente<br/>CLI · MCP · dashboard<br/>finestre di sorgente · SHA-256"]
- Indicizza. Ogni file è analizzato con le grammatiche tree-sitter incluse. Gli adattatori estraggono dichiarazioni, punti di chiamata e riferimenti e li risolvono con regole esplicite per ogni linguaggio. I casi irrisolti o ambigui restano registrati come tali, non vengono indovinati.
- Conserva. Grafo e indice full-text stanno in un solo file SQLite,
.code-graph/graph.db, aggiornati nella stessa transazione. La reindicizzazione rianalizza solo i file il cui hash è cambiato. - Interroga. Ricerca e letture del sorgente verificano che i file citati corrispondano ancora agli hash registrati e rifiutano le evidenze superate finché non reindicizzi. Esegui
indexdopo ogni modifica: le ricerche per nome comefindeshowrispondono dall’ultimo indice. - Consegna. I risultati tornano come JSON delimitato: il sorgente da leggere, perché è stato scelto e cosa è stato omesso.
La sola ricerca testuale trova la funzione il cui nome contiene le tue parole. Le sfugge la funzione che questa chiama per fare il lavoro vero, e il test che la esercita, perché raramente ripetono le stesse parole. La ricerca di code-graph combina i due segnali, interamente dentro SQLite, senza embedding e senza modelli:
flowchart LR
Q["Richiesta<br/>“cancel order”"] --> L["① FTS5 / BM25<br/>colonne pesate:<br/>nome 8 · firma 3 · percorso 2 · corpo 1"]
L -->|"primi 50 per testo"| R
L -->|"3 semi migliori"| X["② Espansione sul grafo<br/>chiamanti + chiamati, profondità ≤ 3<br/>filtro di confidenza, limiti rigidi"]
X -->|"ordinati per distanza,<br/>supporto, confidenza"| R["③ Reciprocal Rank Fusion<br/>punteggio = Σ 1 / (60 + posizione)"]
R --> O["④ Evidenze entro il budget<br/>finestra di sorgente + SHA-256<br/>posizione BM25 · posizione nel grafo · arco testimone<br/>omissioni esplicite"]
- Ordinamento lessicale. FTS5 assegna a ogni dichiarazione un punteggio BM25 su nome, firma, percorso e i primi 2.000 caratteri del corpo. Gli identificatori sono spezzati ai confini
snake_caseecamelCase, quindistartHTTPServercorrisponde a HTTP server. Quando le parole esatte lasciano spazio, la richiesta si allarga con le radici delle parole (cancelling →cancel*) e con sinonimi comuni di programmazione (abort →cancel); questi risultati vengono dopo quelli esatti e sono marcatiexpanded. - Espansione sul grafo. Le tre migliori corrispondenze testuali diventano semi. code-graph percorre chiamate e riferimenti risolti in entrambe le direzioni (profondità predefinita 2), entro limiti fissi di 500 nodi e 1.000 archi per richiesta, e dichiara quando un limite viene raggiunto.
- Fusione. La Reciprocal Rank Fusion unisce le due classifiche usando solo le posizioni, così un punteggio BM25 e una distanza nel grafo non vanno mai messi sulla stessa scala. Ogni simbolo conta una volta per canale; i pareggi si risolvono per percorso e riga, quindi i risultati sono deterministici.
- Evidenze, non solo nomi. Ogni risultato dice perché è lì: la posizione testuale e il punteggio BM25, oppure l’arco di chiamata esatto (file, riga, direzione, confidenza) che lo collega a un seme. Le finestre di sorgente portano gli hash e l’intera risposta rispetta il tuo budget di caratteri.
Un esempio concreto. In un piccolo progetto di checkout, la richiesta cancel order restituisce quattro risultati (output reale di cg search, abbreviato):
| Risultato | Perché è stato restituito |
|---|---|
checkout.py: void_purchase |
corrispondenza testuale: la sua docstring dice Cancel order (posizione BM25 2) |
preview.py: obsolete_cancel_order |
corrispondenza sul nome (posizione BM25 1): un’esca che non fa nulla |
ledger.py: record_adjustment |
grafo: chiamata da void_purchase in checkout.py:4, confidenza alta |
tests/test_checkout.py: test_reversal |
grafo: chiama void_purchase alla riga 2, confidenza alta |
Né record_adjustment né test_reversal contengono le parole cancel od order: la sola ricerca testuale non può trovarle, eppure sono proprio ciò che un agente deve leggere ed eseguire prima di cambiare il flusso di annullamento.
Misurato sul banco di prova della ricerca. Sette richieste sintetiche fra Python, TypeScript e PHP, ciascuna con simboli pertinenti dichiarati (casi, risultati):
| Modalità | Simboli pertinenti fra i primi 5 | Reciprocal rank medio | Tempo mediano¹ |
|---|---|---|---|
Solo testo (--mode lexical) |
9 su 15 (recall@5 media 0,62) | 0,93 | 28 ms |
| Ibrida testo + grafo RRF (predefinita) | 15 su 15 (recall@5 media 1,00) | 1,00 | 28 ms |
¹ Mediana per richiesta su un portatile, apertura dell’indice inclusa. I casi sono piccoli e costruiti a mano per esercitare il meccanismo: non sono una misura generale di accuratezza. Sui repository reali l’espansione vale quanto gli archi risolti per ciascun linguaggio (copertura). Rigenera le cifre con python3 -I benchmarks/search_retrieval.py --output … e python3 -I tools/readme_charts.py.
cg --root . search "cancel order" # ibrida, evidenze JSON (predefinita)
cg --root . search "cancel order" --mode lexical # solo BM25, per confrontoLo stesso motore è disponibile come strumento MCP cg_search e nella barra di ricerca della dashboard (Testo + grafo). Contratto completo: docs/SEARCH.md.
Ogni cifra qui sotto viene da una ricevuta salvata in benchmarks/ e i grafici sono rigenerati da quei file con tools/readme_charts.py. Fallimenti e risultati negativi sono pubblicati insieme al resto.
L’indicizzazione regge SDK reali, e restare aggiornati costa poco. Dopo il primo indice code-graph rianalizza solo i file il cui contenuto è cambiato: sul Go SDK da 2,2 milioni di righe la modifica di un file si reindicizza in 9 s e un progetto invariato si ricontrolla in 3 s. Il Go SDK superava il limite di 600 secondi; indicizzare per package i candidati degli import l’ha portato a 52 s, con fatti identici sul sottoinsieme di confronto (dettagli).
| Progetto | Righe | File | Indice completo | Nessuna modifica | Un file modificato | Picco di memoria | Richiesta, testo / ibrida |
|---|---|---|---|---|---|---|---|
| Generato, 8 linguaggi | 10.000 | 62 | 0,36 s | 0,11 s | 0,13 s | 60 MiB | 31 / 31 ms |
| Generato, 8 linguaggi | 100.110 | 623 | 2,49 s | 0,21 s | 0,42 s | 118 MiB | 50 / 51 ms |
| Dart SDK 3.6 | 208.759 | 433 | 4,33 s | 0,19 s | 0,48 s | 143 MiB | 70 / 77 ms |
| Generato, 8 linguaggi | 1.000.091 | 6.226 | 26,99 s | 1,24 s | 3,58 s | 731 MiB | 209 / 234 ms |
| Go SDK go1.27.4 | 2.233.479 | 7.035 | 52,31 s | 3,15 s | 9,16 s | 1.038 MiB | 814 / 1.037 ms |
Osservazioni singole su macOS ARM64 con Python 3.13 su un desktop in uso; le richieste sono mediane di tre campioni a cache calda di una sola richiesta. Il Dart SDK ha 29 file e il Go SDK 65 che il parser non legge del tutto; code-graph li segna come parziali e su di loro si astiene (Dart, Go).
Il grafo trova il codice che la ricerca testuale perde. Sul banco di prova della ricerca, la ricerca ibrida mette fra i primi cinque tutti e 15 i simboli pertinenti contro 9 su 15 del solo testo, con lo stesso tempo di risposta (grafico e avvertenze). Su dieci richieste parafrasate con parole diverse da quelle del codice (cancelling orders, free the mutex) ora trova 22 simboli pertinenti su 22, contro 11 su 22 prima dell’aggiunta di radici e sinonimi (casi: casi di sviluppo scritti da chi ha implementato la funzione, non un test indipendente). I casi sono piccoli e sintetici: mostrano il meccanismo, non una misura generale di accuratezza.
La versione migliorata di locate è stata congelata e misurata una sola volta su 45 bug storici di Django, typescript-eslint e Prometheus, scelti con una regola fissata prima di ogni esecuzione: un file della correzione storica è il primo candidato in 23 casi su 44 (main prima della modifica: 10) e fra i primi cinque in 30 (main: 17); la funzione cambiata è fra le prime cinque in 16 su 41 (main: 7). Allo stesso budget di 4.000 caratteri è 28 su 44: il guadagno viene soprattutto dall'ordinamento, non dalla risposta più lunga. Una correzione fatta dopo il congelamento costava 7 primi posti sugli stessi casi; la release 1.9.0 ripristina l'ordine valutato e lì ottiene 23 su 44, 30 su 44 e 18 su 41, con una nuova esecuzione fatta dopo aver visto i risultati e quindi non alla cieca. Misura solo la localizzazione, non gli agenti. benchmarks/locate-bench/RESULTS.md.
Gli studi sui coding agent riportano esiti, token, costi e chiamate fallite, con il dettaglio per compito.
"$CG" explore # apre il browser
"$CG" explore --workspace /percorso/progetti --no-open # stampa invece l’indirizzoUn’applicazione web locale su 127.0.0.1 con porta casuale e token di sessione; esplorazione e ricerca non avviano mai un modello. Italiano o inglese, tema chiaro, scuro o di sistema. Premi ⌘K / Ctrl+K per cercare.
Vicinato del simbolo, impatto e test. Fai clic su una funzione per vedere chiamanti e chiamati come grafo, il sorgente con i riferimenti registrati, ogni punto di chiamata in entrambe le direzioni e i test raggiunti attraverso le catene di chiamanti (elencati, mai eseguiti). La scheda Contesto agente costruisce un pacchetto per quel simbolo entro un budget di caratteri.
Altre viste: guida al progetto, architettura e risorse, efficienza
Guida al progetto. Da dove iniziare in questo progetto, i sei passi che segue un agente e un incarico pronto da incollare per una modifica, una domanda d’impatto, un errore, una spiegazione o un controllo finale.
Architettura e risorse. Letture e scritture di file, connessioni a database e avvii di processi trovati nel sorgente, tenuti separati dalle chiamate: un percorso scritto nel codice non prova un collegamento fra due processi. SQLite SQL ha una sezione propria con dichiarazioni, letture e scritture esplicite, candidati delimitati nello stesso script e finestre di sorgente con hash. L’SQL non viene mai eseguito.
Funzionalità → Capisci e modifica. Parti da una scheda di funzionalità dichiarata o da un punto d’ingresso candidato; segui flusso, contratti e test riconosciuti; costruisci un pacchetto di contesto per l’agente, poi confronta firme, codice e punti di chiamata dopo la modifica.
Efficienza. Misura ogni lettura della dashboard: dimensione, latenza e scheda sorgente rispetto alla lettura di tutte le sezioni. I token sono stimati come caratteri Unicode / 4 e i risparmi negativi restano visibili.
Se un sorgente consultato, una configurazione o l’indice cambiano, la dashboard chiede di aggiornare l’analisi prima di mescolare coordinate vecchie e codice nuovo.
La Mappa tecnica conserva funzioni, file e chiamate statiche. La Mappa funzionale parte da un nome come Pagamento o Ordini, poi apre il codice collegato, l’impatto e i test proposti. Nomi e appartenenza sono dichiarazioni del progetto; le frecce richiedono evidenze di chiamate statiche dirette. I candidati tecnici restano separati quando lo scopo non è dichiarato.
La stessa panoramica è disponibile al motore e agli agenti: cg flows "Pagamento" --json o MCP
cg_flows, poi cg_prepare sull’ID dichiarato selezionato. Evita di espandere tutte le funzionalità
solo per sceglierne una; non è una promessa misurata di risparmio di token LLM. La guida alle due mappe
spiega dichiarazioni, limiti ed esempi. Apri Guida all’uso nell’intestazione della dashboard per orientarti con schede visive e accedere subito alle viste.
Affida una modifica a Codex o Claude e seguila fino all’integrazione. Un modello scrive, l’altro rilegge, e i due passi decisivi restano tuoi:
Analizza → Capisci → Piano (✅ approvi tu) → Modifica → Verifica → Revisione e integrazione (✅ decidi tu)
- Capisci. Fai domande in sola lettura, anche su un simbolo scelto sulla mappa. Descrivi la modifica e scegli autore e revisore (di norma l’altro modello).
- Piano. L’autore propone file, parti coinvolte, test, rischi e domande aperte. code-graph controlla ogni simbolo nell’indice, aggiunge l’impatto calcolato dal grafo ed elenca ciò che non è visibile al grafo. Scegli perimetro e comando di test, poi approvi.
- Modifica. code-graph esegue prima i test approvati; l’autore modifica un worktree Git isolato, mai il tuo checkout.
- Verifica. code-graph reindicizza la copia e riesegue i test. Nuovi fallimenti, errori, tempi scaduti o file fuori perimetro bloccano la modifica.
- Revisione e integrazione. L’altro modello risponde accetta, chiedi modifiche o rifiuta, con i rilievi. Puoi rimandarla all’autore (fino a tre giri), scartarla o integrarla.
Confini di sicurezza, integrazione e comandi da terminale
- Consenso. Nessun agente parte senza il tuo consenso per la sessione, ricontrollato subito prima di ogni avvio. Da riga di comando
cg change plan,editereviewchiedono conferma (o--yes) e senza terminale rifiutano. - Passi in sola lettura. Domande, piano e revisione non possono scrivere: Codex gira nel sandbox
read-only; Claude in modalità plan con soloRead,Grep,Globe gli strumenti MCP di code-graph. - Scrittura solo nella copia isolata
<progetto>/.code-graph/worktrees/<id>, sul branchcg/change-<id>. Codex:workspace-write, nessuna shell. Claude:acceptEdits, nessunBash. - Nessuna configurazione del progetto. Claude non carica hook né impostazioni del progetto analizzato e riceve solo il server MCP di code-graph. Codex parte con
--ignore-user-config --ignore-rules, quindi il tuoconfig.toml(provider, profilo, modello predefinito) non viene usato. - Solo code-graph esegue i test, con il comando approvato, senza shell, entro 600 secondi. code-graph non esegue mai
git push. - Costo. Ogni esecuzione ha un limite di tempo e usa l’account del client installato. Per Claude puoi fissare un tetto di spesa in USD per modifica (
--budget-usd) e per le domande; Codex non ha un’opzione equivalente. - Integrazione. Lascia la modifica sul suo branch (predefinito) oppure uniscila a un checkout pulito con
git merge --no-ff, senza hook Git né firma; in caso di conflitto l’unione viene annullata. L’integrazione richiede un verdetto diverso da rifiuta e nessun blocco di verifica, salvo una motivazione che resta nello storico. Scarta rimuove copia e branch; l’archivio in.code-graph/changes/<id>/resta. - L’output dei test resta in quell’archivio: un test che stampa un segreto ve lo lascia.
"$CG" --root /percorso/progetto change new --intent "Rinomina work in compute" --author codex --reviewer claude
"$CG" --root /percorso/progetto change plan <id> --yes
"$CG" --root /percorso/progetto change approve <id> --test-argv '["python3","-m","unittest"]'
"$CG" --root /percorso/progetto change edit <id> # --feedback "…" per un nuovo giro
"$CG" --root /percorso/progetto change verify <id>
"$CG" --root /percorso/progetto change review <id>
"$CG" --root /percorso/progetto change integrate <id> # --merge, --force-reason "…"Ogni comando attende il suo passo e stampa JSON; sono disponibili anche list, show, discard e cancel.
Dalla cartella in cui hai installato code-graph, puoi indicizzare un progetto e vedere un esempio di cosa chiedere:
scripts/cg --root /percorso/progetto startSul repository di code-graph stesso stampa (percorsi abbreviati, testo in italiano con LANG=it_* o --lang it):
472 file sorgente: troppi da leggere uno a uno. È il caso per cui code-graph è pensato:
trovare il codice di una richiesta, l’impatto di una modifica e i test da lanciare.
1. Cosa si rompe se lo cambio, e quali test devo lanciare?
prepare è chiamata da 13 punti; attraverso quelle chiamate la raggiungono 13 test.
$ cg --root . impact scripts/features.py:prepare --depth 3
$ cg --root . verify scripts/features.py:prepare --plan
2. Dov’è il codice di una richiesta?
$ cg --root . search prepare
3. La mia modifica ha toccato qualcosa che non volevo?
$ cg --root . review --base HEAD
Le stesse tre domande aprono la dashboard (cg explore), ciascuna con un pulsante che porta alla vista giusta.
| Vuoi sapere | Comando | Cosa ottieni |
|---|---|---|
| Dove intervenire per una richiesta, in una sola risposta | locate "testo della richiesta" |
I punti probabili da cambiare con codice, chiamanti e test, più quanta lettura ti ha risparmiato (nessun modello; aggiorna prima l’indice) |
| Cosa si rompe se cambio questo, e quali test lanciare | impact <simbolo> · verify <simbolo> --plan |
Chiamanti fino alla profondità che scegli, ciascuno con il punto di chiamata, e i test raggiunti attraverso di loro (elencati, mai eseguiti) |
| Dov’è il codice di una richiesta, in un progetto che non conosci | search "parole" |
Le dichiarazioni pertinenti più le funzioni che chiamano o da cui sono chiamate, con finestre di sorgente e hash |
| Se una modifica ha toccato qualcosa di non voluto | review --base HEAD |
Firme, chiamate e segnalazioni confrontate con l’ultimo commit, più un piano di test |
Ogni comando prende --root <progetto> prima del nome del comando. Esegui index all’inizio e dopo ogni modifica: rianalizza solo i file cambiati.
"$CG" --root /percorso/progetto index
"$CG" --root /percorso/progetto search "cancel order" --max-chars 9000
"$CG" --root /percorso/progetto impact 'OrderService.cancel' --depth 3
"$CG" --root /percorso/progetto context 'OrderService.cancel' --profile change --max-chars 4000
"$CG" --root /percorso/progetto verify 'OrderService.cancel' --plan --json
"$CG" --root /percorso/progetto review --base HEAD --jsonTutti i comandi
| Comando | Cosa ottieni |
|---|---|
start [--lang en|it] [--json] |
Indicizza il progetto e mostra tre domande da porgli, con un esempio reale e i comandi pronti. |
index [--full] |
Crea o aggiorna .code-graph/graph.db; segnala esclusioni e analisi parziali. |
locate TESTO [--limit 5] [--max-chars 5000] |
Dal testo di una richiesta ai punti da cambiare, con codice, chiamanti e test, e la lettura risparmiata. Nessun modello. |
search QUERY [--mode hybrid|lexical] [--max-chars 9000] |
Evidenze JSON ordinate con FTS5/BM25 e RRF sul grafo. |
map [--depth 2] [--limit 25] |
Dimensioni dei moduli, dipendenze, punti caldi e probabili punti d’ingresso. |
find <pattern> [--kind class|method|function] |
Simboli per nome o pattern *. |
show <sym> |
Firma, membri, basi e numero di vicini. |
callers <sym> / callees <sym> |
Vicini con confidenza e un punto di chiamata ciascuno; callees elenca anche chiamate esterne e dinamiche. |
impact <sym> [--depth 3] [--min-conf medium] |
Chiamanti transitivi e test trovati; callback e registrazioni tramite decoratore compaiono come riferimenti. impact <file> --file lavora su un file intero. |
path <A> <B> |
Il percorso di chiamata più breve trovato fra due simboli. |
context <sym> [--max-chars 4000] [--profile understand|change|debug|review] |
Contesto per un agente entro un budget di caratteri, con omissioni dichiarate. |
source <file> [--line N] [--max-chars 1200] |
Una finestra di sorgente delimitata con colonne Unicode e hash. |
features [--query parole] / prepare [scheda] … |
Schede di funzionalità, punti d’ingresso e un pacchetto di contesto per modificarle. |
verify <sym> --plan |
Piano test leggibile con argv per test e aggregato; --json conserva le evidenze strutturate. Una proposta: nulla viene eseguito. |
review [--base REF] [--staged] |
Riepilogo leggibile di baseline, rilievi e test; --json conserva l’analisi strutturata del diff. |
check / dead [--all] |
Candidati: arità, metodi mancanti, duplicati, cicli; simboli senza chiamanti noti. |
architecture / stats |
Osservazioni sulle risorse separate dalle chiamate; copertura dell’indice. |
export [--symbol <sym>] [--depth 2] |
Un grafo HTML offline autonomo (nessun server, rete o CDN). |
explore / mcp |
La dashboard; il server MCP su stdio. |
change … |
Il flusso di modifica da terminale. |
selftest |
25 controlli sulle fixture: TRUST o DISTRUST. |
<sym> può essere nome, Classe.metodo, Classe::metodo, percorso/file.php:nome o percorso/file.php:123; ripeti un nome ambiguo con il percorso o la classe. La maggior parte dei comandi accetta --json; la sintassi completa è in SKILL.md.
"$CG" --root /percorso/progetto mcpUn server MCP su stdio con quindici strumenti: cg_locate, cg_search, cg_flows, cg_find, cg_show, cg_callers, cg_callees, cg_impact, cg_verify_plan, cg_prepare, cg_source, cg_read, cg_review, cg_check e cg_index. Nessuno strumento cambia i tuoi sorgenti o esegue il codice analizzato; cg_index aggiorna solo la cache .code-graph. Le risposte si fermano a 40.000 caratteri con un marcatore esplicito. Il flusso di modifica passa questo server a Codex e Claude automaticamente.
Prompt d’esempio
Se cambio OrderService.cancel, quali parti possono essere coinvolte? Elenca i test che lo raggiungono.
Prepara il contesto per correggere questo errore: [errore]. Mostrami i riferimenti nel codice.
Ricostruisci il flusso da CheckoutController.submit a OrderRepository.save ed elenca i passi che il grafo non ha risolto.
Confronta prima e dopo questa modifica: cosa è cambiato e quali controlli servono ancora?
Usa il flusso di modifica di code-graph su questo progetto: Codex scrive, Claude rilegge. Mostrami piano e comando di test prima di qualsiasi approvazione: [descrizione].
Ogni linguaggio ha un contratto scritto: cosa viene risolto e dove l’analisi si astiene di proposito invece di indovinare. Non servono compilatori, SDK o language server.
| Linguaggio | Cosa viene risolto | Contratto |
|---|---|---|
| Python | Import e riesportazioni, ricevitori tipizzati, callback e decoratori, moduli caricati con importlib/runpy, route FastAPI/Flask |
LANGUAGES |
| JavaScript / TypeScript | Moduli ES e CommonJS, barrel, path di tsconfig, pacchetti workspace, componenti JSX |
LANGUAGES |
| PHP | Namespace, import di funzioni e classi, callback, hook WordPress | LANGUAGES |
| Go | Chiamate fra package e import, ricevitori concreti espliciti; interfacce e varianti di build si astengono | GO |
| Dart | Librerie, import relativi e package: locali, metodi statici; il dispatch d’istanza si astiene |
DART |
| Java | Sottoinsieme dichiarato static/private/final; overload e dispatch virtuale si astengono | JAVA |
| Swift | Sottoinsieme private/static nel file; overload e import si astengono | SWIFT |
| SQLite SQL | Tabelle, viste e query con osservazioni di lettura/scrittura, separate dalle chiamate | SQL |
- Una guida, non una prova. Le confidenze
high,mediumelowdescrivono come è stata risolta una chiamata, non che venga eseguita. Dispatch dinamico, reflection, dependency injection e route registrate come stringhe possono lasciare archi mancanti o errati. - Lessicale, non semantica. La ricerca usa le parole che scrivi, le loro radici e un piccolo elenco di sinonimi comuni di programmazione; non traduce una domanda e non usa embedding. Chiedi all’agente di riformulare la richiesta in termini di codice: la guida alla ricerca per agenti lo fa.
- Solo candidati.
checkedeadproducono candidati da confermare;VERIFIED_DEADnon autorizza una cancellazione. - Cosa viene indicizzato. Dipendenze incluse, cartelle di build, file ignorati da Git, link simbolici, file oltre 1 MB e file minificati sono esclusi; aggiungi pattern in
.cgignore. - Dati locali.
.code-graph/graph.dbcontiene metadati ed estratti di sorgente. Si esclude da solo da Git; non pubblicarlo. Vedi PRIVACY.md. - Misure. I risultati di scala descrivono i repository e l’hardware usati. Lo studio con gli agenti copre 23 bug storici in tre repository, con un’esecuzione per variante.
- Lingua dell’interfaccia. Riga di comando, messaggi del motore e guida sono in inglese; dashboard,
cg starte questo README sono in italiano e inglese. Le chiavi JSON sono in inglese.
scripts/cg selftest
.venv/bin/python -I tools/parallel_tests.py # l’intera suite in processi paralleli1.9.0 — locate, test da lanciare, scala di Django e localizzazione misurata
locate. Un solo comando da una richiesta, una issue o uno stack trace ai punti da cambiare, con sorgente, chiamanti e test, entro un budget di caratteri e con la lettura risparmiata. Richieste fino a 200.000 caratteri; su 45 bug storici un file della correzione è il primo candidato in 23 casi su 44 (main prima: 10). Risultati.- Test da lanciare.
verifyereviewpropongono comandi pronti per pytest, unittest, Go, Jest/Vitest e PHPUnit (con il Python del progetto) e stampano un riepilogo breve e leggibile;review --summary --jsonè una risposta compatta per gli agenti. - Scala di Django. La risoluzione degli import Python è indicizzata: Django si indicizza in 18 s invece di 98 s e
review --baseimpiega 40 s invece di oltre 600 s, con fatti identici (ricevuta). - Documentazione e lingua. Una guida completa con esempi reali e un riferimento generato dal codice; riga di comando, messaggi del motore e SKILL.md in inglese.
- Risultati dei benchmark. Il benchmark di localizzazione e lo studio su 23 bug storici includono i protocolli e i risultati per ogni caso. Benchmark
- Correzioni dal campo. I metodi degli enum PHP non sono più segnalati come mancanti;
cg startnon esce più in silenzio quando la funzione d'esempio ha un nome ambiguo. Licenza FSL-1.1-MIT.
Versioni precedenti
- 1.8.0 — Avvio guidato (
cg starte il riquadro Inizia da qui della dashboard), Go alla scala di un SDK (52 s per 2,2 milioni di righe), un pilota su repository reale con SymPy e i benchmark nel README. - 1.7.0 — Ricerca ibrida locale (SQLite FTS5/BM25 con RRF sul grafo), adattatori Go, Dart, Java e Swift, mappe delle risorse SQLite SQL e indicazioni di ricerca nel flusso di modifica.
- 1.6.5 — Catalogo API locale (
cg catalog), decoratori e ricevitori Python più precisi, più route FastAPI/Flask, correzioni a moduli e riferimenti JS/TS,relationnell’impatto JSON. - 1.6.4 — Più chiamanti trovati tramite riesportazioni Python e ricevitori tipizzati, callback e comandi registrati come riferimenti, barrel e alias di percorso JS/TS, import di funzioni PHP; meno falsi candidati di codice morto.
- 1.6.3 — Chiamanti dei moduli caricati con
importliborunpy. - 1.6.2 — Flusso di modifica più stabile con percorsi di piano non validi, link creati dai test, output MCP e segnali su macOS.
- 1.6.1 — Conferma da riga di comando prima di avviare un agente, tetto di spesa per Claude, dashboard più stabile ed esecuzione parallela dei test.
- 1.6.0 — Modifica con un agente: sei passi, worktree isolato, test prima e dopo, revisione dell’altro modello; il server MCP.
- 1.5 — Finestre di sorgente delimitate; Capisci e modifica con schede di funzionalità e pacchetti di contesto.
- 1.4 — Contesto entro un budget di caratteri, revisione dei diff con piano di test, pannello Efficienza, italiano/inglese e temi chiaro/scuro.
Storia completa: CHANGELOG.md.
code-graph è libero da usare e cresce con chi lo usa, segnala cosa il grafo non vede e ne parla.
Se code-graph ti è utile, lascia una stella su GitHub ⭐ e sostieni il mio lavoro con un contributo su Ko-fi.
Chi contribuisce al codice compare nella pagina dei contributori di GitHub. Sponsorizzazioni di persone e organizzazioni sono benvenute: contribuisci su Ko-fi o apri una issue per parlarne.
- Segnala un problema o proponi un’idea nelle issue. Per un problema di sicurezza segui SECURITY.md.
- Contribuisci con una pull request; esegui prima
selfteste la suite di test. I contributi sono accettati con la licenza del progetto. - Raccontaci come va sui tuoi progetti: cosa ha aiutato l’agente, cosa mancava, cosa il grafo non vedeva.
- Lascia una stella ⭐ al repository e condividilo se aiuta il tuo team.
FSL-1.1-MIT: uso, modifica e condivisione liberi per ogni scopo tranne un prodotto o servizio concorrente; ogni versione diventa MIT due anni dopo l’uscita · Sviluppato da Stefano D’Agostino · GitHub





