Wat is Graft voor coding agents?

Wat een codebase-map voor coding agents is

Een codebase-map voor coding agents is een persistente index van uw repository waarin de agent informatie opzoekt, in plaats van dat deze in elke nieuwe sessie vanaf nul door de bestanden moet zoeken (greppen). Graft is een implementatie van dat concept. Het parseert uw code met tree-sitter, schrijft een map met gekoppelde markdown-nodes inclusief een wiring-graph per symbool, en stelt retrieval-tools beschikbaar via MCP (model context protocol, de standaardinterface die coding agents gebruiken om externe tools aan te roepen).

Graft is geen proxy en geen gateway. Er bevindt zich niets tussen uw agent en de model-API. De map is een directory op de schijf die de agent uitleest. Dat onderscheid bepaalt welk probleem u oplost: een self-hosted token gateway meet en routeert de verzoeken die u al verstuurt, terwijl een map het aantal verzoeken dat u überhaupt moet versturen, vermindert.

De techniek is ouder dan deze tool en zal deze overleven. Leer eerst de techniek, en daarna de werking.

Waarom coding agents context verspillen door het herontdekken van de structuur

Observeer een agent die begint te werken aan een repository die hij al vijftig keer heeft gezien. Hij somt mappen op. Hij voert grep uit op een symbool. Hij opent drie bestanden om te achterhalen welke de functie definieert, en vervolgens een vierde om te zien wie deze aanroept. Niets daarvan is de eigenlijke taak. Het is oriëntatie, en het wordt bij elke sessie betaald in input tokens.

De oorzaak is simpel. Een model heeft geen geheugen tussen sessies. Alles wat de agent leerde over uw structuur bevond zich in een contextvenster dat werd weggegooid toen de sessie eindigde. Dus begint dezelfde ontdekkingstocht telkens opnieuw vanaf nul, tegen de volle prijs. Bij een grote repository kost de oriëntatiefase meer dan de bewerking zelf: tien tool-aanroepen om de code te lokaliseren, één om deze te wijzigen. Oriëntatie is slechts de helft van de rekening en de bewerking de andere, wat de reden is waarom een vaardigheid die de agent dwingt tot de kleinst mogelijke wijziging die werkt het waard is om te combineren met een kaart, in plaats van tussen beide te kiezen.

Een kaart doorbreekt die lus door de ontdekking te verplaatsen van het model naar de schijf. Een parser doorloopt de repository één keer, legt vast welk symbool waar is gedefinieerd en welk symbool welk ander aanroept, en houdt dat overzicht actueel naarmate de code verandert. De agent stelt één vraag en krijgt een antwoord inclusief bestand en regelnummer. Herhaalde verkenning wordt zo een goedkope opzoekactie.

U gebruikt al een zwakkere versie hiervan. Een AGENTS.md die uw conventies beschrijft voorkomt dat de agent elke keer opnieuw uw conventies moet afleiden. Een gegenereerde kaart voorkomt dat hij telkens opnieuw uw structuur moet afleiden. Het verschil zit in wie het schrijft. U schrijft het instructiebestand met de hand, dus het blijft klein. Een parser genereert de kaart, waardoor deze tienduizenden bestanden kan beslaan. Voor inzicht in waar het budget binnen een sessie daadwerkelijk naartoe gaat, behandelt hoe Claude Code zijn contextvenster besteedt de verantwoording.

Wat Graft daadwerkelijk bouwt

Twee artefacten, beide onder één graft/-map in de hoofdmap van de repository.

Het eerste is een knooppuntgraaf geschreven als gelinkte markdown, één bestand per knooppunt. Elk knooppunt bevat een samenvatting in begrijpelijke taal, een "kern" van de belangrijke logische regels die uit de broncode zijn gehaald, de exacte bronbestanden met een inhoudshash, getypeerde wikilinks naar andere knooppunten (depends_on, part_of, uses, implements), en een notitiesectie die behouden blijft na regeneratie, zodat u context kunt vastleggen die een parser niet kan afleiden.

Het tweede is graft/.graph/wiring.json, de structurele graaf per symbool die tree-sitter extraheert: definities, verwijzingen en de aanroepverbindingen daartussen.

Deze splitsing is van belang omdat slechts de helft een model vereist. graft build is pure tree-sitter en roept nooit een LLM (large language model) aan; het is dus deterministisch en kost niets. graft build --deep voegt de geschreven samenvattingen en de kernen per symbool toe, en dat zijn modelaanroepen waarvoor u betaalt.

Taalondersteuning is ingedeeld in niveaus, en het niveau geeft aan in hoeverre u de aanroepgraaf kunt vertrouwen. TypeScript, JavaScript, Python, Go en Java beschikken over scope-bewuste cross-file resolutie. Rust, C, C++, C#, Ruby, PHP, Kotlin, Scala, Swift, Elixir, Solidity, OCaml, Zig en Dart krijgen symbolen plus generieke aanroepverbindingen, wat betekent dat een verbinding een naamovereenkomst kan zijn in plaats van een opgeloste verwijzing. Verbindingen van compiler-kwaliteit zijn optioneel beschikbaar via --lsp en een language server zoals rust-analyzer of gopls.

Graft installeren en de versie vastzetten

Graft vereist Node.js 20 of nieuwer en is uitgebracht onder de MIT-licentie. Per augustus 2026 is de huidige release 0.10.1, en de eerste gepubliceerde versie, 0.1.0, dateert van juli 2026. Behandel het als nieuwe software.

npm install -g @nanonets/graft@0.10.1
npm ls -g @nanonets/graft

npm ls -g hoort @nanonets/graft@0.10.1 weer te geven. Zet deze versie bewust vast. Een kale npm install -g @nanonets/graft lost de latest-tag op op het moment dat u het uitvoert. Bij een project dat meerdere minor-releases per maand uitbrengt, betekent dit dat u op dinsdag een ander hulpmiddel heeft dan uw collega op maandag heeft geïnstalleerd. Een vastgezette versie houdt de CLI-flags en het grafiekformaat voor iedereen gelijk, zodat u pas upgradet wanneer u dat besluit.

Koppel het vervolgens aan een repository die u beheert:

cd /path/to/your/repo
graft init --dry-run
graft init

graft init vraagt welke van uw coding agents u wilt koppelen en bouwt daarna de grafiek. Voer eerst --dry-run uit en lees de lijst met bestanden die het programma van plan is te wijzigen, aangezien sommige daarvan zich buiten de repository bevinden. graft init is idempotent en overschrijft bestaande configuraties niet, dus het is veilig om dit een tweede keer uit te voeren.

Per augustus 2026 dekt de koppeling Claude Code, Cursor, Codex, GitHub Copilot, Google Gemini, Kiro, Windsurf en AdaL. Claude Code krijgt de diepste integratie: een MCP-server-entry, een statusregel die de grootte en veroudering van de grafiek toont, post-edit hooks die de grafiek opnieuw opbouwen, en een skill-bestand onder .claude/. De overige krijgen een instructie- of regelbestand dat de agent vertelt dat de tools bestaan. "Ondersteund" betekent daarom dat Graft de koppeling schrijft; een agent die zijn eigen regelbestand negeert, zal dus ook de kaart negeren. Dat is de gebruikelijke reden waarom agents de instructies die u voor hen schrijft negeren, en dat is hier net zozeer van toepassing als elders.

Wat wordt er in uw repository opgenomen en wat blijft buiten git

Na graft init kunt u het volgende verwachten:

• graft/: de markdown-nodegrafiek en graft/.graph/wiring.json. Deze worden automatisch toegevoegd aan .gitignore.
• .mcp.json: registreert de graft MCP-server zodat Claude Code deze opstart.
• .claude/settings.json: wordt op de juiste plek samengevoegd en voegt de statusregel en de post-edit hooks toe.
• AGENTS.md, GEMINI.md, .github/copilot-instructions.md, .cursor/rules/graft.mdc, .kiro/steering/graft.md, .windsurf/rules/graft.md en .adal/skills/graft/SKILL.md: secties met marker-fencing die worden toegevoegd aan de bestanden die overeenkomen met de door u gekozen agents.
• ~/.codex/config.toml, ~/.codex/hooks.json en ~/.codex/hooks/graft/graft-hooks.cjs: machinebreed, worden alleen geschreven wanneer u Codex selecteert. graft init --no-global slaat deze over en graft init --no-hooks slaat de hook-shim zelfstandig over.

De grafiek is een cache, vergelijkbaar met node_modules. Commit deze niet. De grafiek wordt binnen enkele seconden opnieuw gegenereerd op basis van de code, verandert bij vrijwel elke bewerking en het committen ervan verandert een correctie van één regel in een diff van honderden bestanden die geen enkele reviewer zal lezen. Commit in plaats daarvan de configuratie, waaronder AGENTS.md en .mcp.json. Een teamgenoot kloont de repository, voert graft build uit en krijgt een eigen lokale grafiek.

Controleer of de ignore-regel is toegepast voordat u uw eerste commit uitvoert:

grep -n graft .gitignore
git status --short

grep hoort een regel te tonen die graft/ bevat, en git status --short hoort niets weer te geven onder graft/. Als bestanden onder graft/ in die uitvoer verschijnen, betekent dit dat de ignore-vermelding ontbreekt of elders wordt overschreven. Herstel dit voordat u commit, omdat git een bestand blijft volgen zodra het is toegevoegd; een latere .gitignore-bewerking zal het bestand niet uit de tracking verwijderen.

Als u de MCP-server liever handmatig registreert of wilt vastzetten op de versie die u heeft geïnstalleerd, is de vermelding kort:

{
  "mcpServers": {
    "graft": {
      "command": "npx",
      "args": ["-y", "@nanonets/graft@0.10.1", "mcp"]
    }
  }
}

De zoektools die uw agent aanroept in plaats van grep

Graft stelt zes tools beschikbaar via MCP. graft_find_code retourneert gerangschikte nodes voor een taakomschrijving, inclusief bestand en regelnummer. graft_file_api retourneert elke signatuur in een bestand zonder de bijbehorende body. graft_trace_calls doorloopt aanroepers of aangeroepenen over meerdere niveaus. graft_find_all retourneert regex-treffers gegroepeerd per symbool. graft_repo_map biedt een eerste overzicht van een onbekende repository. graft_check_freshness rapporteert of de graaf nog overeenkomt met de code.

Elke tool heeft een CLI-equivalent; hiermee controleert u wat uw agent daadwerkelijk ontvangt:

graft map .
graft ask "where do we validate the refresh token"
graft skeleton src/auth/session.ts
graft callers validateRefreshToken
graft callers validateRefreshToken --direction out
graft grep "refresh_token" --json

graft ask hoort gerangschikte nodes te printen met file:line-referenties in plaats van bestandsinhoud. Dit is het volledige mechanisme: de agent ontvangt een pointer en opent één bestand, in plaats van er tien te lezen om de juiste te vinden. graft viz opent een interactieve viewer op localhost als u de graaf zelf wilt bekijken. Als graft ask niets nuttigs retourneert voor een vraag die u in dertig seconden zelf kunt beantwoorden, dan is de graaf verouderd of valt uw taal in de brede categorie, en zal de kaart uw agent ook niet helpen.

Eén kostenpost wordt vaak over het hoofd gezien. Zes tooldefinities worden bij elk verzoek gedurende de hele sessie in de system prompt geïnjecteerd. U betaalt deze kosten ongeacht of de agent de kaart gebruikt of niet. Bij een repository die klein genoeg is om in de context te passen, kan deze vaste last groter zijn dan de besparing die de verkenning oplevert.

Wat gebeurt er met de graaf wanneer de code wijzigt

Een structurele verversing is goedkoop en automatisch. Graft leest uw werkmap in plaats van git, waardoor een wijziging die u nog niet heeft gecommit en een wijziging die u heeft gestaged even zichtbaar zijn. Een query parseert alleen de bestanden opnieuw waarvan de stat-informatie is gewijzigd; de documentatie van het project spreekt van ongeveer 3 ms overhead. Een herbouw aan het einde van een bewerking raakt alleen bestanden aan waar code is verplaatst. Stel GRAFT_NO_REFRESH=1 in of gebruik --no-refresh om antwoord te krijgen vanuit de graaf op schijf zonder opnieuw te parsen. Gebruik --no-reuse om een volledige koude her-parsing af te dwingen; dit is wat u wilt na het upgraden van Graft zelf.

Het door het model geschreven deel gedraagt zich anders en dit is het onderdeel dat ongemerkt fout kan gaan. Samenvattingen en kernpunten worden gecachet. Elk knooppunt registreert een content-hash van zijn bronnen, dus wanneer een bronbestand wijzigt, wordt het knooppunt als verouderd gemarkeerd in plaats van als actueel gepresenteerd. Die vlag helpt alleen als er actie op wordt ondernomen. Ververs met graft build --deep, wat opnieuw model-tokens verbruikt.

Maak veroudering zichtbaar:

graft check .
echo $?

Exit-status 0 betekent dat de graaf overeenkomt met de code. Exit-status 1 betekent afwijking. Voer dit uit vanuit een pre-push hook, of op de branch in CI, zodat een kaart van zes maanden oud niet met zekerheid antwoord kan geven over code die in maart is herschreven.

Bestudeer de gepubliceerde benchmarkcijfers zorgvuldig

De belangrijkste claim van Graft is "tot 4x goedkoper en 3x sneller, met betere of gelijkblijvende correctheid". Deze cijfers zijn afkomstig uit de eigen benchmarks van het project, zoals gepubliceerd in de README. Hieronder staan de twee runs die volledig worden gerapporteerd.

[
  {
    "label": "Controlled sweep",
    "run_count": 162,
    "token_saving_pct": 42,
    "tool_call_saving_pct": 46,
    "correctness_pct": 93,
    "baseline_correctness_pct": 93
  },
  {
    "label": "SWE-bench Verified",
    "run_count": 50,
    "token_saving_pct": 23,
    "tool_call_saving_pct": 25,
    "correctness_pct": 66,
    "baseline_correctness_pct": 54
  }
]

De gecontroleerde sweep bestaat uit 162 runs over twee repositories, waarvan één Graft zelf, met drie pogingen per taak. Het rapporteert 42% minder tokens en 46% minder tool calls. De SWE-bench Verified run omvat 50 instances met hetzelfde model voor beide scenario's, en rapporteert een kleinere besparing: 23% aan tokens en 25% aan tool calls. Een derde run reproduceerde vijf gemergde PocketBase pull requests tegen een kostprijs van 11.02 US dollar, vergeleken met 13.91 voor de baseline.

Beschouw dit alles als een leveranciersbenchmark. Twee factoren beperken de waarde van deze informatie. De gecontroleerde sweep bevat de eigen repository van Graft, de codebase waarop de auteurs hun tool hebben afgesteld. SWE-bench Verified is een publieke dataset met issues uit bekende open-source Python-projecten, en publieke datasets zijn de bronnen waarop tools worden geoptimaliseerd, of dit nu bewust gebeurt of niet. Geen van beide is een uitspraak over uw eigen private monorepo, die zijn eigen naamgevingsconventies en dode code bevat.

Correctheid verdient een tweede lezing. Bij de gecontroleerde sweep veranderde deze niet: 93% met de map tegenover 93% zonder. De sprong naar 66% vanaf 54% is alleen zichtbaar bij SWE-bench Verified. Een tool die uw tokenkosten verlaagt en de kwaliteit gelijk houdt, is nog steeds een goede deal. Combineer echter niet het correctheidsresultaat van SWE-bench met het tokenresultaat van de sweep om deze als één enkele claim te presenteren.

Meet uw eigen tokendelta voordat u de cijfers gelooft

Het enige getal dat ertoe doet, is het getal uit uw eigen repository. Deze methode kost een middag werk.

Kies een taak die u exact kunt herhalen. Een vraag is beter dan een bewerking, omdat een bewerking de repository wijzigt en de tweede run niet langer hetzelfde experiment is. "Welke module dwingt de rate limit af op de login-route" is de juiste vorm.

Schakel telemetrie in en stuur deze naar uw eigen terminal:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console
claude

De console-exporter print metriekrecords zodra ze worden verzameld. De metriek die u nodig heeft is claude_code.token.usage, die een type-attribuut draagt van input, output, cacheRead of cacheCreation. De oriëntatie is zichtbaar in input en cacheRead, omdat daar de bestandsinhoud terechtkomt. Tel deze twee bij elkaar op.

Voer de taak drie keer uit, telkens in een nieuwe sessie, met de map gekoppeld. Verwijder daarna de graft-vermelding uit .mcp.json en voer de taak nog drie keer uit. Vergelijk de medianen in plaats van individuele runs, omdat agent-runs sterk variëren en één ongelukkige run u het tegenovergestelde van de waarheid kan vertellen. Noteer ook het aantal tool-calls: tool-calls zijn het mechanisme en tokens zijn het effect; een besparing op tokens zonder afname in tool-calls betekent dus dat er iets anders is veranderd.

Trek vervolgens de kosten af die de benchmark niet laat zien. graft build --deep verbruikt model-tokens bij elke volledige verversing. De zes tool-schema's reizen mee in elk verzoek. Als uw agents op een gehuurde server draaien, verandert het instellen van een hard plafond op agent-uitgaven dit van een verrassing in een budget, en wat de telemetrie van een coding agent daadwerkelijk rapporteert behandelt wat de machine verlaat zodra u de exporter inschakelt.

Wanneer is een codebase-map niet langer nuttig?

• De repository past al in de context. Een kleine service heeft geen map nodig, terwijl u wel voor zes tool-schema's per verzoek betaalt. Als uw agent vandaag bestanden vindt met slechts één of twee tool-aanroepen, sla de map dan over.
• Uw programmeertaal valt in de brede categorie. Generieke aanroep-edges betekenen dat graft callers een aanroeper kan missen of een foutieve aanroeper kan genereren door een naamconflict. Controleer dit met graft grep voordat u vertrouwt op een impactanalyse (blast radius).
• De graaf is verouderd en niemand merkt het op. graft check geeft exitcode 1 bij afwijkingen, wat alleen nuttig is als het proces ook daadwerkelijk wordt uitgevoerd. Maak er een CI-stap of hook van, geen gewoonte.
• De monorepo heeft scoping nodig. Een monorepo met één git-repository wordt automatisch gesplitst op basis van workspace-bestanden, go.mod, pyproject.toml of Cargo.toml, en graft ask "..." --in services/billing/ beperkt een query tot één subproject. Hetzelfde instinct dat leidt tot geneste AGENTS.md-bestanden per pakket is van toepassing op de map.
• De agent negeert de configuratie. Observeer de tool-aanroepen in een echte sessie voordat u concludeert dat de map wordt gebruikt. Een agent die nog steeds grep uitvoert, geeft aan dat het regels-bestand nooit is gelezen.

FAQ

Moet ik de map graft/ toevoegen aan git?

Nee. graft build voegt graft/ automatisch toe aan uw .gitignore, omdat de graaf een herberekenbare cache is, vergelijkbaar met node_modules. Deze verandert bij vrijwel elke bewerking; het toevoegen ervan aan git zou echte wijzigingen (diffs) verbergen onder honderden gegenereerde bestanden. Voeg de configuratie toe die agents vertelt dat de kaart bestaat, waaronder AGENTS.md en .mcp.json, en laat elk teamlid graft build lokaal uitvoeren. Controleer dit met grep -n graft .gitignore en git status --short vóór uw eerste commit, omdat git een bestand blijft volgen zodra het is toegevoegd; het bewerken van .gitignore achteraf verwijdert het bestand niet uit de tracking.

Kost het draaien van Graft geld?

Het structurele gedeelte niet. graft build, graft ask, graft check en de zes MCP-retrieval-tools zijn tree-sitter-operaties die nooit een model aanroepen. graft build --deep is het betaalde gedeelte: dit schrijft de samenvattingen in begrijpelijke taal en de kernpunten per symbool via een LLM, geconfigureerd met GRAFT_PROVIDER, GRAFT_API_KEY en GRAFT_MODEL, plus GRAFT_BASE_URL voor elk OpenAI-compatibel eindpunt. U kunt Graft alleen met de structuur draaien zonder ooit een token aan de graaf zelf uit te geven.

Hoeveel bespaart een codebase-kaart daadwerkelijk op mijn repository?

Niemand kan u dat vertellen zonder metingen. Het project rapporteert 42% minder tokens bij zijn eigen 162-run sweep en 23% op SWE-bench Verified, beide afgezet tegen een baseline zonder kaart. Dit zijn beide leveranciersbenchmarks, waarvan er één deels op de eigen repository van Graft is uitgevoerd, en geen van beide beschrijft uw private code. Voer één herhaalbare vraag drie keer uit met de kaart en drie keer zonder, met CLAUDE_CODE_ENABLE_TELEMETRY=1 en OTEL_METRICS_EXPORTER=console ingesteld, en vergelijk vervolgens de mediaan van claude_code.token.usage voor de typen input en cacheRead.

Wat gebeurt er met de graaf wanneer ik refactor?

De structuur parseert zichzelf opnieuw. Graft controleert de werkmap (working tree) en parseert alleen de bestanden die zijn gewijzigd. Een hernoeming wordt bij de volgende query opgepikt met ongeveer 3 ms overhead, en het ziet niet-gecommitteerd werk omdat het bestanden leest in plaats van de git-historie. De door het model geschreven samenvattingen raken verouderd: elk knooppunt slaat een content-hash van zijn bronnen op, en een gewijzigde bron markeert het knooppunt als verouderd in plaats van het te herschrijven. Voer graft check . uit om de afwijking te zien, en vervolgens graft build --deep om het geschreven gedeelte te verversen.

Welke coding agents kunnen Graft vandaag gebruiken?

Sinds augustus 2026 graft init ondersteunt Graft Claude Code, Cursor, Codex, GitHub Copilot, Google Gemini, Kiro, Windsurf en AdaL. Claude Code krijgt de meeste functionaliteit: een MCP-serververmelding in .mcp.json, een statusregel, post-edit hooks en een skill-bestand onder .claude/. Codex krijgt een AGENTS.md-sectie plus machinebrede vermeldingen onder ~/.codex/, die graft init --no-global overslaat. De overige ontvangen een regels- of sturingsbestand. Elke andere MCP-client kan de server direct gebruiken door het commando npx -y @nanonets/graft@0.10.1 mcp te registreren.