Ridurre i token di un agente di coding: dagli una mappa, non tutta la codebase
Ridurre i token di un agente di coding è un problema di struttura, non di dimensione della finestra di contesto. code-review-graph è uno strumento open source che costruisce una mappa strutturale di una codebase e la espone agli agenti via MCP, in modo che leggano soltanto i file che servono davvero. Il repository di tirth8205 ha superato le 29.400 stelle su GitHub, è distribuito con licenza MIT, e si presenta con una riga che dice già tutto: "Stop burning tokens. Start reviewing smarter."
Il modo in cui Claude Code, Cursor e Codex capiscono un progetto è ancora, in sostanza, questo: cercano, aprono file, leggono, e continuano finché non hanno abbastanza per rispondere. Su un repository di dieci file non si nota niente. Su un monorepo vero si paga due volte, una in fattura e una in qualità, perché un modello con dentro quarantamila righe di contesto irrilevante ragiona peggio di uno che ne ha davanti quattrocento pertinenti.
Cosa fa davvero una mappa della codebase
Una mappa della codebase è un grafo delle dipendenze del progetto, costruito leggendo il codice una volta sola e interrogato molte. code-review-graph usa Tree-sitter per analizzare i sorgenti e ne ricava nodi, cioè funzioni, classi e import, collegati da archi che rappresentano chiamate, ereditarietà e copertura dei test. Il risultato finisce in un file SQLite dentro la cartella .code-review-graph/ del repository, e resta lì.
Da quel grafo discende la cosa interessante, che la documentazione del progetto chiama blast radius: "When a file changes, the graph traces every caller, dependent, and test that could be affected." Tradotto in pratica, quando tocchi un file lo strumento sa dirti chi lo chiama, chi dipende da lui e quali test lo coprono, senza che nessuno debba leggere il resto del progetto per scoprirlo.
Il progetto copre oltre quaranta linguaggi, fra cui Python, JavaScript, TypeScript, Go, Rust, Java, C, C++, C#, Ruby, PHP, Kotlin e Swift, e si registra come server MCP su Claude Code, Cursor, Codex, Windsurf, Zed, Continue, OpenCode, Gemini CLI e GitHub Copilot. All'agente espone una trentina di strumenti, e i nomi dicono a cosa servono: get_minimal_context_tool per ottenere il contesto minimo, get_impact_radius_tool per il raggio di impatto di una modifica, get_architecture_overview_tool per la panoramica dell'architettura.
Quanti token si risparmiano davvero
Il benchmark pubblicato da code-review-graph misura sei repository e riporta una riduzione mediana di circa 65 volte per domanda, con un intervallo che va da 36 a 376 volte. Su fastapi il confronto è fra 948.793 token e 2.653, cioè 375,6 volte. Su flask fra 143.594 e 2.196, cioè 71 volte. Su express, il caso peggiore della tabella, fra 136.052 e 3.936, cioè 36 volte.
Qui va detta una cosa che nella tabella si legge solo guardando l'intestazione delle colonne. Il termine di paragone è "Tokens (Corpus)", cioè il costo di mettere l'intero repository dentro il contesto. Nessuno lavora così. Claude Code e Cursor non caricano tutta la codebase: fanno grep, aprono i file che sembrano rilevanti e si fermano. Il confronto onesto non è fra il grafo e il corpus intero, è fra il grafo e quella ricerca approssimativa, e quel numero il benchmark non lo misura.
Quindi no, non risparmierete 65 volte sulla bolletta. Il guadagno vero sta altrove, e conta di più: la ricerca testuale trova i file che contengono una parola, il grafo trova i file che dipendono da una funzione. Sono due insiemi diversi, e il secondo è quello giusto. Un agente che rompe un chiamante che non aveva letto costa molto più caro di qualche migliaio di token.
L'altra strada: comprimere invece di selezionare
Comprimere il modo in cui l'agente scrive è la seconda famiglia di strumenti che promette di ridurre i token, e il caso più visto è caveman, la skill di JuliusBrussee che ha superato le 100.000 stelle su GitHub e che ha pubblicato la versione 2.2.0 il 20 agosto 2026. L'idea è far scrivere all'agente in modo telegrafico invece di fargli leggere meno file.
Il numero che circola è il 65% medio di token di uscita risparmiati, con un intervallo che il README dichiara fra il 22% e l'87%. Lo stesso README però mette accanto un avviso intitolato "Honest number warning" e vale più della percentuale: la skill riduce soltanto i token di uscita, lascia intatti quelli di ingresso e quelli di ragionamento, e aggiunge da sola circa 1.000-1.500 token di ingresso a ogni turno. Sui carichi già asciutti, scrive il progetto, il risparmio netto può diventare negativo.
Il numero onesto dello stesso progetto sta altrove: il proxy caveman, che agisce sull'ingresso, dichiara "33.2% fewer provider-reported input tokens" su un benchmark Claude Code di 54 esecuzioni con tutti e 18 i controlli di risposta esatta superati. È un terzo, non due terzi, ed è misurato sulla parte che pesa davvero in fattura.
Come ridurre i token di un agente di coding, con e senza strumenti
L'installazione di code-review-graph è tre comandi, e il secondo è quello che lo collega al vostro agente.
Dopo il primo build non serve ricostruire ogni volta: il progetto prevede aggiornamenti incrementali con code-review-graph update e una modalità code-review-graph watch che tiene il grafo allineato mentre si lavora. Vale la pena impostarla subito, perché un grafo vecchio è peggio di nessun grafo: l'agente si fida di una mappa che non descrive più il codice che ha davanti.
Se non volete installare niente, la versione povera dello stesso principio funziona già e costa mezz'ora. Scrivete a mano il file di istruzioni del progetto e metteteci dentro la struttura, non le buone intenzioni: dove stanno le cose, come sono organizzate le cartelle, quali alias di percorso esistono, dove si aggiunge un tipo nuovo di contenuto. È la stessa idea del grafo, fatta a mano e senza aggiornamento automatico, ed è il primo passo di quello che ho descritto parlando di context engineering per i modelli Claude 5.
Questo sito è l'esempio che ho sottomano. Alla radice del repository c'è un CLAUDE.md che elenca i gruppi di route, la tabella dei percorsi, dove stanno gli articoli del blog, come funziona la pipeline MDX e il fatto che @/* punta a ./src/*. Non calcola nessun raggio di impatto, ma evita all'agente di aprire venti file per capire dove va messo un articolo nuovo. Lo stesso ragionamento l'ho applicato alle regole di scrittura del blog, divise in tre file dentro .claude/skills/articolo/ e caricate solo quando servono, invece di stare tutte dentro un prompt unico che viaggia a ogni richiesta.
Cosa cambia per chi costruisce con l'AI
La direzione è chiara: il contesto smette di essere una cosa che l'agente si va a prendere e diventa una cosa che il progetto gli fornisce. Sono due modelli diversi di responsabilità. Nel primo la qualità dipende da quanto è bravo l'agente a cercare, nel secondo dipende da quanto bene è descritto il repository, ed è una variabile su cui potete lavorare voi.
Il fatto che code-review-graph sia local-first è la parte che rende la cosa adottabile sul lavoro vero. Il grafo si costruisce e si interroga dentro il repository, e anche nella versione GitHub Action la documentazione specifica che tutto resta sul runner della CI. Chi lavora su codice di clienti sa perché è la prima domanda da fare, ed è la stessa che mi sono posto scrivendo di quali permessi dare all'AI in azienda.
Resta una cautela che vale per tutti gli strumenti di questa famiglia. Un server MCP che espone trenta funzioni al vostro agente è trenta modi in più di consumare il contesto che volevate risparmiare, e il grafo va comunque tenuto aggiornato da qualcuno. Prima di aggiungere infrastruttura conviene misurare quanto costa oggi una sessione tipica, perché se il collo di bottiglia è il modo in cui è organizzato il progetto, nessun grafo lo sistema al posto vostro. Se invece state già coordinando più sessioni di Claude Code che si parlano fra loro, una mappa condivisa del repository è esattamente il pezzo che manca.
La finestra di contesto è cresciuta per anni e il problema non si è risolto, il che di solito vuol dire che stavamo guardando la variabile sbagliata. Non serve che l'agente possa leggere tutto. Serve che sappia cosa non leggere.
Fonte primaria: il repository tirth8205/code-review-graph su GitHub.
Domande frequenti
Cos'è MCP e perché serve per dare il contesto a un agente di coding?
MCP è il protocollo con cui un agente di coding come Claude Code o Cursor si collega a strumenti esterni e li usa come funzioni. Serve al contesto perché permette all'agente di chiedere un'informazione precisa a uno strumento invece di ricostruirla leggendo file. Un server MCP che conosce la struttura di un repository può rispondere quali file toccare senza che l'agente li apra tutti.
code-review-graph funziona con Cursor o solo con Claude Code?
code-review-graph si registra come server MCP su una lista lunga di client, fra cui Claude Code, Cursor, Codex, Windsurf, Zed, Continue, OpenCode, Gemini CLI e GitHub Copilot. Il comando che fa il collegamento è code-review-graph install. Non è legato a un singolo fornitore di modelli, perché il grafo vive nel repository e non dentro l'agente.
Il codice viene inviato a un server esterno?
No. code-review-graph è dichiarato local-first e costruisce il grafo dentro il repository, in un file SQLite nella cartella .code-review-graph/. Anche quando gira come GitHub Action, la documentazione del progetto specifica che il grafo viene costruito e interrogato sul runner della CI, senza trasmettere il codice sorgente all'esterno. Resta vero che l'agente collegato via MCP manda comunque al proprio modello i pezzi di codice che decide di leggere.
Serve ricostruire il grafo ogni volta che modifico il codice?
No, il progetto prevede aggiornamenti incrementali con il comando update e una modalità watch che tiene il grafo allineato in automatico mentre si lavora. La ricostruzione completa con build serve la prima volta o dopo cambiamenti molto estesi. Un grafo non aggiornato è peggio di nessun grafo, perché l'agente si fida di una mappa vecchia.
Quanto contesto serve davvero a un agente per modificare un file?
Dipende da quante altre parti del progetto dipendono da quel file, non dalla dimensione del progetto. Servono il file stesso, chi lo chiama, cosa chiama lui e i test che lo coprono. È esattamente l'insieme che un grafo delle dipendenze sa calcolare e che una ricerca testuale approssima leggendo molto più del necessario.