Graft: ein Dateigraphen statt Vektorindex als Kontextschicht für Coding-Agents

Das Problem, das Graft adressiert: Agents explorieren jede Aufgabe neu

Coding-Agents beginnen jede Aufgabe ohne Vorwissen über das Repository. Sie greppen einen Begriff, öffnen eine Datei, folgen einem Import, verwerfen den Ansatz und versuchen es erneut. Das README beschreibt diesen Vorgang als Wiederaufbau eines Bildes, das der Agent eine Stunde zuvor schon einmal gezeichnet und dann weggeworfen hat. Die Kosten sind dreifach: Der Aufwand fällt bei jeder Aufgabe erneut an, das Ergebnis überlebt die Sitzung nicht, und der nächste Entwickler samt Agent beginnt wieder bei null. Der Satz aus dem README, Menschen würden einmal an ein Repository herangeführt, Agents dagegen jedes Mal, bringt die Zielgruppe auf den Punkt. Graft richtet sich an Teams mit großen, gewachsenen Codebasen, in denen ein Agent pro Sitzung viele Dateien anfassen muss, und die dafür einen MCP-fähigen Agenten wie Claude Code, Cursor, Codex oder Gemini einsetzen. Für ein Repository mit einer Handvoll Dateien ist der Explorationsaufwand ohnehin gering, dort gibt es wenig zu sparen.

Der Mechanismus: verlinkte Markdown-Dateien statt Embeddings

Graft legt das Verständnis der Codebasis einmal ab und schreibt es als Ordner zusammenhängender Markdown-Dateien in das Repository, einen Knoten pro System, API oder Konzept. Die Dokumentation beschreibt jeden Knoten als Erklärung in einfacher Sprache: was ein Teil des Systems tut und wie er mit dem Rest verbunden ist, so wie es ein erfahrener Entwickler erklären würde. Ausdrücklich kein Abzug von Funktionsnamen, sondern Prosa, die ein Agent lesen kann, um die Exploration zu überspringen. Der zweite Teil des Mechanismus ist die Abfrage: Der Graph ist eine Menge verlinkter Dateien, die der Agent öffnet, greppt und deren Verweisen er folgt, genauso wie er jede andere Datei im Repository liest. Das README nennt das ausdrücklich als Abgrenzung: keine Embeddings, keine Ähnlichkeitssuche, kein Index, der warmgehalten werden muss. Der Agent bekommt also keinen Vektorraum als Zwischenschicht, sondern das Dateisystem selbst als Schnittstelle. Das ist eine bewusste Designentscheidung mit Folgen, denn sie verschiebt die Qualität des Ergebnisses vom Retrieval-Modell auf die Qualität der generierten Knoten.

Installation und Verdrahtung in zwei Befehlen

Der Einstieg ist im README knapp gehalten. Zuerst wird die CLI global installiert, danach folgt die Initialisierung:

npm install -g @nanonets/graft graft init

Der zweite Befehl fragt, welche Coding-Agents angebunden werden sollen, baut den Ordner graft/ aus dem Code und legt eine Statuszeile sowie Hooks in .claude/ ab. Ab der nächsten Sitzung zieht Graft passende Knoten in jeden Prompt und baut den Graphen im Hintergrund nach jeder Runde neu auf. Laut README läuft dafür kein Daemon, und es gibt keinen Index, an den man sich erinnern müsste. Wer zuerst sehen will, was passiert, nutzt graft init --dry-run; wer die Rückfrage überspringen und nur Claude Code anbinden will, nutzt graft init --agents claude. Wer keine globale Installation möchte, verwendet npx @nanonets/graft init. Der Befehl graft build trägt graft/ automatisch in .gitignore ein, weil der Graph als lokaler, regenerierbarer Cache gilt, vergleichbar mit node_modules. Geteilt wird über das Repository nur die Verdrahtung in .claude/, die per git add .claude eingecheckt wird; jeder im Team erzeugt seinen eigenen Graphen mit graft build.

Was der Graph nicht leistet und wo er das falsche Werkzeug ist

Der dateibasierte Ansatz hat eine klare Bruchstelle: Er hilft nur, wenn die Knoten tatsächlich erklären, was der Agent braucht. Ein Graph, der nur Struktur abbildet, ersetzt die Exploration nicht, weil der Agent dann trotzdem Code lesen muss. Das README formuliert den Anspruch selbst, dass es sich nicht um eine Auflistung von Symbolen handelt, sondern um Erklärungen. Ob ein konkreter Knoten diesen Anspruch einlöst, lässt sich erst nach einem Lauf im eigenen Repository beurteilen. Ein zweiter Punkt ist die Aktualität. Der Graph wird nach jeder Runde im Hintergrund neu gebaut, aber er bleibt ein Cache und kann veralten, wenn Arbeit außerhalb des verdrahteten Agenten stattfindet, etwa bei einem Wechsel der Branches oder bei Änderungen, die direkt in der IDE entstehen. Wer den Graphen eincheckt, statt ihn zu ignorieren, handelt gegen die ausdrückliche Empfehlung des READMEs und erzeugt Konflikte zwischen Teammitgliedern. Und wer einen Agenten einsetzt, der nicht in der Liste der unterstützten Integrationen auftaucht, hat von Graft nichts, weil die Anbindung über MCP und die Claude-Code-Hooks läuft.

Abgrenzung zu Vektorindex-Lösungen

Die naheliegende Alternative ist ein Embedding-basierter Index über die Codebasis, wie ihn viele Retrieval-Werkzeuge für Agents aufbauen. Der Unterschied liegt im Datenmodell. Ein Vektorindex ordnet Textabschnitte in einem hochdimensionalen Raum an und liefert bei einer Anfrage die ähnlichsten Treffer zurück; die Auswahl bleibt eine Ähnlichkeitsrechnung, deren Ergebnis der Agent nicht ohne Weiteres nachvollziehen kann. Graft verzichtet laut README genau darauf und setzt stattdessen auf einen Graphen aus verlinkten Markdown-Dateien, dem der Agent durch Öffnen und Greppen folgt. Damit ist jeder Schritt im Dateisystem sichtbar und reproduzierbar, und es gibt keinen Index, dessen Aktualität über Erfolg oder Misserfolg entscheidet. Der Preis dafür ist, dass keine unscharfe Suche möglich ist. Ein Vektorindex findet bei einer vage formulierten Frage möglicherweise relevante Stellen, die im Graphen schlicht nicht verlinkt sind. Wer viele natürlichsprachliche Ad-hoc-Fragen an eine Codebasis stellt, ist mit einem Retrieval-Index besser bedient; wer wiederkehrende Aufgaben in einem stabilen Repository bearbeitet, profitiert stärker von einem einmal gebauten, lesbaren Graphen.

Behauptete Kennzahlen und was sie nicht belegen

Das README stellt eine Tabelle mit Zahlen gegenüber: 46 Prozent weniger Tool-Aufrufe, 42 Prozent Token-Einsparung, 60 Prozent Zeitersparnis und ein Anstieg der Korrektheit von 54 auf 66 Prozent, jeweils im Vergleich zu Claude Code ohne Graft. Die Überschrift nennt bis zu viermal günstiger und dreimal schneller. Diese Werte stammen aus der Projektdokumentation, nicht aus einer unabhängigen Messung, und sie sind an eine bestimmte Aufgabe, ein bestimmtes Modell und einen bestimmten Zeitpunkt gebunden. Wer die Zahlen als Planungsgrundlage für ein Budget verwenden will, muss sie im eigenen Repository und mit dem eigenen Agenten nachvollziehen. Ein weiterer Hinweis auf die Reife: Für das Projekt wurden zum Zeitpunkt der Erhebung keine Releases abgerufen, die Verteilung läuft über das npm-Paket @nanonets/graft. Die Lizenz ist MIT, was die Weitergabe und Anpassung erlaubt, solange der Urheberrechtshinweis erhalten bleibt; das ist keine Rechtsberatung, und wer den Code in ein Produkt einbettet, sollte die Lizenzbedingungen selbst prüfen.

Wartungsaufwand und Betrieb im Team

Der Betrieb ist auf geringen Aufwand ausgelegt. Nach der Installation über npm install -g @nanonets/graft und graft init läuft der Graph laut README ohne Daemon und ohne manuelle Neuindizierung; graft build regeneriert ihn, und nach jeder Agentenrunde wird er im Hintergrund nachgezogen. Der Aufwand liegt damit nicht im Betrieb, sondern in der Verteilung. Weil graft/ in .gitignore landet, muss jedes Teammitglied den Graphen lokal erzeugen. Die gemeinsam versionierte Datei ist die Verdrahtung unter .claude/, und Änderungen daran laufen durch denselben Review wie jeder andere Commit. Das ist ein klarer Vorteil gegenüber Lösungen, die einen zentralen Indexdienst betreiben, aber es bedeutet auch, dass die Qualität des Graphen pro Arbeitskopie neu entsteht. Ein Upgrade der CLI ist ein npm-Vorgang; ob ein neuer Stand den Graphen neu aufbaut oder die Verdrahtung anpasst, lässt sich aus dem vorliegenden Material nicht ableiten, und dafür wäre ein Blick in die Änderungshinweise des Pakets nötig.

Redaktionelles Fazit

Graft passt zu Teams, die Claude Code oder einen anderen MCP-fähigen Agent auf einer großen, langlebigen Codebasis betreiben und den Explorationsaufwand pro Aufgabe senken wollen; wer nur gelegentlich an kleinen Repositories arbeitet, gewinnt wenig, weil der Graph selbst gepflegt und neu gebaut werden muss. Vor der Einführung zuerst graft init --dry-run ausführen und prüfen, welche Dateien unter .claude/ angelegt werden, danach graft build laufen lassen und kontrollieren, dass graft/ tatsächlich in .gitignore steht, und erst dann den Graphen ins Team-Repository einchecken.

Offizielle Quellen

1. Issues
2. License: MIT
3. Project website
4. README
5. trailhq/Graft on GitHub