SSD Nodes Learn Hosting plans →
Anleitungen Matt ConnorVon Matt Connor

Graft: Codebase-Karte für Coding-Agenten

Graft analysiert Ihr Repository mit tree-sitter und stellt über MCP eine abfragbare Codebase-Karte bereit, damit der Agent Strukturen nicht in jeder Sitzung neu ermittelt.

Was eine Codebase-Karte für Coding-Agenten ist

Eine Codebase-Karte für Coding-Agenten ist ein dauerhafter Index Ihres Repositorys. Der Agent schlägt darin Informationen nach, statt sich in jeder neuen Sitzung durch wiederholtes Greppen von Grund auf zu orientieren. Graft ist eine Implementierung dieses Konzepts. Das Tool analysiert Ihren Code mit tree-sitter, schreibt einen Ordner mit verknüpften Markdown-Knoten sowie einen Wiring-Graphen pro Symbol und stellt Abrufwerkzeuge über MCP (model context protocol, die Standardschnittstelle für Aufrufe externer Werkzeuge durch Coding-Agenten) bereit.

Graft ist weder ein Proxy noch ein Gateway. Zwischen Ihrem Agenten und der Model API befindet sich keine zusätzliche Komponente. Die Karte ist ein Ordner auf der Festplatte, den der Agent liest. Diese Unterscheidung bestimmt, welches Problem Sie lösen: ein selbst gehostetes Token-Gateway erfasst und leitet die Anfragen weiter, die Sie bereits senden, während eine Karte die Anzahl der Anfragen ändert, die Sie überhaupt senden müssen.

Die Technik ist älter als dieses Tool und wird es überdauern. Lernen Sie zuerst die Technik und anschließend die Mechanismen kennen.

Warum Coding-Agenten Kontext für die erneute Ermittlung der Struktur verbrauchen

Beobachten Sie, wie ein Agent die Arbeit an einem Repository beginnt, das er bereits fünfzigmal gesehen hat. Er listet Verzeichnisse auf. Er sucht mit grep nach einem Symbol. Er öffnet drei Dateien, um herauszufinden, in welcher die Funktion definiert ist, und dann eine vierte, um festzustellen, wer sie aufruft. Nichts davon gehört zur eigentlichen Aufgabe. Es dient der Orientierung und wird in jeder einzelnen Sitzung mit Eingabetokens bezahlt.

Die Ursache ist einfach. Ein Modell hat zwischen Sitzungen kein Gedächtnis. Alles, was der Agent über Ihr Layout gelernt hat, befand sich in einem Kontextfenster, das beim Ende der Sitzung verworfen wurde. Daher beginnt dieselbe Ermittlung jedes Mal wieder bei null, und Sie bezahlen erneut dafür. Prompt-Caching gewährt nur einen Rabatt für einen identischen Prompt-Präfix, der innerhalb der letzten fünf Minuten oder gegen Aufpreis innerhalb der letzten Stunde gesehen wurde. Die Erkundung vom Vortag kann daher nicht in die heutige Sitzung übernommen werden. Bei einem großen Repository kostet die Orientierungsphase mehr als die Änderung selbst: zehn Tool-Aufrufe, um den Code zu finden, und einer, um ihn zu ändern. Die Orientierung macht nur die eine Hälfte dieser Kosten aus, die Änderung die andere. Deshalb lohnt es sich, eine Fähigkeit, die den Agenten auf die kleinste funktionierende Änderung festlegt, mit einer Übersicht zu kombinieren, statt zwischen beiden zu wählen.

Eine Übersicht durchbricht diese Schleife, indem sie die Ermittlung vom Modell auf den Datenträger verlagert. Ein Parser durchläuft das Repository einmal, erfasst, wo welches Symbol definiert ist und welches Symbol welches andere aufruft, und hält diese Aufzeichnung bei Änderungen am Code aktuell. Der Agent stellt eine Frage und erhält eine Antwort mit Datei und Zeile. Wiederholte Erkundung wird zu einer kostengünstigen Abfrage.

Sie verwenden bereits eine schwächere Variante davon. Eine AGENTS.md, die Ihre Konventionen festlegt, verhindert, dass der Agent Ihre Konventionen jedes Mal erneut herleitet. Eine generierte Übersicht verhindert, dass er Ihre Struktur erneut herleitet. Der Unterschied liegt darin, wer sie erstellt. Sie verfassen die Anweisungsdatei manuell, daher bleibt sie klein. Ein Parser generiert die Übersicht, sodass sie zehntausend Dateien abdecken kann. Für die Frage, wofür das Budget innerhalb einer Sitzung tatsächlich verwendet wird, behandelt wie Claude Code sein Kontextfenster nutzt die Kostenaufstellung.

Was Graft tatsächlich erstellt

Zwei Artefakte, beide in einem graft/-Verzeichnis im Repository-Stammverzeichnis.

Das erste Artefakt ist ein als verknüpftes Markdown-Dokument angelegter Knotengraph mit einer Datei pro Knoten. Jeder Knoten enthält eine Zusammenfassung in einfachem Englisch, einen „Crux“ mit den wichtigen Logikzeilen aus dem Quellcode, die exakten Quelldateien mit einem Inhaltshash, typisierte Wikilinks zu anderen Knoten (depends_on, part_of, uses, implements) sowie einen Notizabschnitt. Dieser bleibt bei der erneuten Generierung erhalten, sodass Sie dort Kontext dokumentieren können, den ein Parser nicht ableiten kann.

Das zweite Artefakt ist graft/.graph/wiring.json, der strukturelle Graph pro Symbol, den tree-sitter extrahiert: Definitionen, Referenzen und die Aufrufkanten zwischen ihnen.

Diese Aufteilung ist wichtig, weil nur eine Hälfte ein Modell benötigt. graft build basiert vollständig auf tree-sitter und ruft niemals ein LLM (large language model) auf. Das Ergebnis ist deterministisch und verursacht keine Kosten. graft build --deep ergänzt die schriftlichen Zusammenfassungen und die Cruxes pro Symbol. Dafür fallen kostenpflichtige Modellaufrufe an.

Die Sprachunterstützung ist nach Stufen gegliedert. Die Stufe gibt an, wie weit Sie einem Aufrufgraphen vertrauen können. TypeScript, JavaScript, Python, Go, Java, Kotlin, PHP, Swift und R erhalten eine bereichsbezogene Auflösung über mehrere Dateien hinweg. Rust, C, C++, C#, Ruby, Scala, Elixir, Solidity, OCaml, Zig, Dart, Clojure, Nix und Lua erhalten Symbole sowie generische Aufrufkanten. Eine Kante kann daher auf einem Namensvergleich statt auf einer aufgelösten Referenz beruhen. Compiler-gestützte Kanten sind mit --lsp und einem Language Server wie rust-analyzer oder gopls optional aktivierbar.

Graft installieren und die Version festlegen

Graft benötigt Node.js 20 oder neuer und steht unter der MIT-Lizenz. Am 17. Oktober 2026 ist 0.23.0 das aktuelle Release. Es wurde am 15. Oktober 2026 veröffentlicht. Die erste veröffentlichte Version, 0.1.0, stammt aus dem Juli 2026. Behandeln Sie die Software als jung. Release 0.22.0, veröffentlicht am 14. Oktober 2026, benannte das Projekt in Trail-code um: Derselbe Code wird jetzt auch als @trailhq/trail-code mit einem trail-Befehl ausgeliefert, während @nanonets/graft den graft-Befehl beibehält.

Diese Anleitung legt 0.21.1 fest. Diese Version wurde am 29. September 2026 veröffentlicht und ist das letzte Release vor der Umbenennung. Der Grund ist, dass 0.22 und 0.23 Befehle geändert haben, auf die sich die Anleitung stützt. Ab 0.22 vergleicht graft check die Änderungen Ihres Branches mit den Team-Erkenntnissen des Repositorys und beendet sich bei einem Konflikt mit dem Exit-Code 1. Die Drift-Erkennung wurde nach graft build --check verschoben. Die MCP-Tools heißen trail_*; der Server antwortet weiterhin auf die alten Namen graft_*. Im Changelog von 0.23.0 steht außerdem, dass sich die Map in einem mit trail eingerichteten Repository nach .trail/cache/ verschiebt und Claude Code keinen MCP-Server mehr erhält. Die README beschreibt dagegen weiterhin graft/ und .mcp.json. Lesen Sie das Changelog und führen Sie --dry-run aus, bevor Sie die festgelegte Version ändern.

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

npm ls -g sollte @nanonets/graft@0.21.1 ausgeben. Legen Sie diese Version bewusst fest. Ein einfaches npm install -g @nanonets/graft löst beim Ausführen den Tag latest auf. Bei einem Projekt, das mehrere Minor-Releases pro Monat veröffentlicht, verwenden Sie dadurch am Dienstag ein anderes Tool als Ihr Kollege, der es am Montag installiert hat. Eine festgelegte Version hält CLI-Flags und Graphformat für alle gleich. So aktualisieren Sie, wenn Sie es entscheiden.

Binden Sie es anschließend in ein Repository ein, das Ihnen gehört:

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

graft init fragt, welche Ihrer Coding-Agents eingerichtet werden sollen, und erstellt anschließend den Graphen. Führen Sie zuerst --dry-run aus und lesen Sie die Liste der Dateien, die der Befehl ändern will. Einige davon liegen außerhalb des Repositorys. graft init ist idempotent und überschreibt keine vorhandenen Konfigurationen. Ein zweiter Aufruf ist daher sicher. Zum Rückgängigmachen entfernt graft uninstall alle Dateien und Konfigurationseinträge, die Graft geschrieben hat. Der Befehl bleibt ein Probelauf, bis Sie -y übergeben.

Im selben Dialog gibt es ein Kontrollkästchen für Telemetrie. Seit Release 0.12.0 sendet Graft standardmäßig einen anonymen Nutzungs-Ping: gruppierte Zählwerte und feste Bezeichnungen, niemals Ihren Code, Dateipfade oder den Namen des Repositorys. Ereignisse werden höchstens einmal täglich übertragen. Eine Ausnahme ist das Installationsereignis: npm übergibt es über seinen postinstall-Hook sofort an den Hintergrundsender. Deaktivieren Sie das Kontrollkästchen während graft init, führen Sie graft telemetry disable aus oder setzen Sie DO_NOT_TRACK=1, um die Telemetrie abzuschalten. In CI wird sie ebenfalls automatisch deaktiviert. graft telemetry debug gibt den Stapel aus, den der Befehl senden würde, ohne ihn zu senden.

In 0.21.1 unterstützt die Einrichtung Claude Code, Cursor, Codex, GitHub Copilot, Google Gemini, Kiro, Windsurf, Grok (xAI), AdaL, Hermes Agent und Google Antigravity. Hermes Agent ist seit Release 0.13.0 ein voll unterstützter graft init-Host. In der festgelegten Version wählen graft init --agents hermes und graft init --agents antigravity diese beiden wie jeden anderen Host aus. Grok kam mit Release 0.13.0 hinzu und wird mit graft init --agents grok ausgewählt. Claude Code erhält die umfassendste Integration: einen MCP-Server-Eintrag, eine Statuszeile mit Graphgröße und Aktualität, Hooks nach Bearbeitungen zum Neuaufbau des Graphen sowie eine Skill-Datei unter .claude/. Die übrigen Agents erhalten eine Anweisungs- oder Regeldatei, die dem Agent mitteilt, dass die Tools vorhanden sind. Hermes Agent und Antigravity lesen beide den Abschnitt AGENTS.md. Grok erhält außerdem einen MCP-Block in seiner eigenen Konfiguration. „Unterstützt“ bedeutet daher, dass Graft die Einbindung schreibt. Ein Agent, der seine eigene Regeldatei nicht berücksichtigt, ignoriert auch die Map. Das ist der gewöhnliche Grund, warum Agents die für sie geschriebenen Anweisungen ignorieren, und hier gilt das ebenso wie anderswo.

Was in Ihr Repository gelangt und was nicht in Git landet

Nach graft init sollten Sie Folgendes vorfinden:

  • graft/: der Markdown-Knotengraph und graft/.graph/wiring.json. Diese Datei wird für Sie zu .gitignore hinzugefügt.
  • .mcp.json: registriert den graft-MCP-Server, damit Claude Code ihn startet.
  • .claude/settings.json: wird an Ort und Stelle zusammengeführt und ergänzt die Statuszeile sowie die Post-Edit-Hooks.
  • AGENTS.md, GEMINI.md, .github/copilot-instructions.md, .cursor/rules/graft.mdc, .kiro/steering/graft.md, .windsurf/rules/graft.md, .grok/skills/graft/SKILL.md und .adal/skills/graft/SKILL.md: durch Marker begrenzte Abschnitte, die an die Dateien angehängt werden, die zu den ausgewählten Agents passen.
  • .grok/config.toml: ein [mcp_servers.graft]-Block auf Repository-Ebene, der nur geschrieben wird, wenn Sie Grok auswählen.
  • ~/.codex/config.toml, ~/.codex/hooks.json und ~/.codex/hooks/graft/graft-hooks.cjs: systemweit, nur geschrieben, wenn Sie Codex auswählen und ~/.codex/ bereits vorhanden ist. graft init --no-global überspringt diese Dateien, und graft init --no-hooks überspringt den Hook-Shim selbstständig.

Der Graph ist ein Cache, ähnlich wie node_modules. Committen Sie ihn nicht. Er wird innerhalb von Sekunden aus dem Code neu erzeugt, ändert sich bei nahezu jeder Bearbeitung, und ein Commit daraus macht aus einer einzeiligen Korrektur ein Diff mit mehreren hundert Dateien, das kein Reviewer lesen wird. Committen Sie stattdessen die Verknüpfungen, einschließlich AGENTS.md und .mcp.json. Ein Teammitglied klont das Repository, führt graft build aus und erhält seinen eigenen lokalen Graphen.

Prüfen Sie vor Ihrem ersten Commit, ob die Ignore-Regel vorhanden ist:

grep -n graft .gitignore
git status --short

grep sollte eine Zeile mit graft/ ausgeben, und git status --short sollte unter graft/ nichts auflisten. Wenn in dieser Ausgabe Dateien unter graft/ erscheinen, fehlt der Ignore-Eintrag oder er wird an anderer Stelle überschrieben. Beheben Sie das vor dem Commit, denn Git verfolgt eine Datei weiter, sobald sie hinzugefügt wurde, und eine spätere Bearbeitung von .gitignore hebt die Nachverfolgung nicht auf.

Wenn Sie den MCP-Server lieber manuell registrieren oder ihn auf dieselbe installierte Version festlegen möchten, ist der Eintrag kurz:

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

Die Abrufwerkzeuge, die Ihr Agent anstelle von grep aufruft

Graft stellt sechs Werkzeuge über MCP bereit. graft_find_code gibt für eine Aufgabenbeschreibung nach Relevanz sortierte Knoten mit Datei und Zeile zurück. graft_file_api gibt jede Signatur in einer Datei ohne Funktionskörper zurück. graft_trace_calls verfolgt Aufrufer oder aufgerufene Funktionen über mehrere Ebenen. graft_find_all gibt Treffer für reguläre Ausdrücke nach Symbol gruppiert zurück. graft_repo_map liefert einen ersten Überblick über ein unbekanntes Repository. graft_check_freshness meldet, ob der Graph noch mit dem Code übereinstimmt.

Jedes dieser Werkzeuge hat ein CLI-Gegenstück. Damit prüfen Sie, welche Informationen Ihr Agent tatsächlich erhält:

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 sollte nach Relevanz sortierte Knoten mit file:line-Referenzen ausgeben, nicht den Dateiinhalt. Das ist der gesamte Mechanismus: Der Agent erhält einen Verweis und öffnet eine Datei, statt zehn Dateien zu lesen, um die richtige zu finden. graft viz öffnet unter localhost eine interaktive Ansicht, wenn Sie den Graphen selbst betrachten möchten. Wenn graft ask für eine Frage, die Sie in dreißig Sekunden beantworten könnten, nichts Verwertbares zurückgibt, formulieren Sie die Frage nicht einfach um und stellen sie erneut. Der Abruf nach Relevanz kann Treffer verfehlen, und die eigene Skill-Datei des Projekts schreibt vor, bei schwachen Treffern zu graft grep, graft skeleton oder graft callers zu wechseln. Wenn auch diese Werkzeuge nicht ausreichen, prüfen Sie, ob eine Abweichung vorliegt (graft check . bei der festgelegten Version 0.21.1, graft build --check ab 0.22), und bestätigen Sie, welcher Tier Ihrer Sprache zugeordnet ist. Ein veralteter Graph oder Kanten aus einem breiten Tier führen bei Ihrem Agenten zum selben Fehler.

Ein Kostenfaktor wird leicht übersehen. Die sechs Werkzeugdefinitionen werden für die gesamte Sitzung in den System-Prompt jeder Anfrage eingefügt. Diese Kosten fallen an, unabhängig davon, ob der Agent die Karte verwendet. Bei einem Repository, das klein genug für den Kontext ist, kann die feste Belastung größer sein als die dadurch eingesparte Exploration.

Was passiert mit dem Graphen, wenn sich der Code ändert

Eine strukturelle Aktualisierung ist kostengünstig und erfolgt automatisch. Graft liest Ihr Arbeitsverzeichnis anstelle von git; daher sind sowohl nicht committete als auch gestagte Änderungen gleichermaßen sichtbar. Jede Abfrage prüft zuerst das Arbeitsverzeichnis und analysiert nur die Dateien neu, die sich geändert haben. Die Dokumentation zu 0.21.1 beziffert diese Prüfung auf etwa 3 ms, wenn sich nichts bewegt hat; das aktuelle README spricht von einigen zehn Millisekunden, etwa 50 ms im eigenen Repository des Projekts. Ein Rebuild am Ende eines Durchlaufs betrifft nur Dateien, in denen sich Code bewegt hat. Setzen Sie GRAFT_NO_REFRESH=1 oder übergeben Sie --no-refresh, um Antworten aus dem Graphen auf der Festplatte zu erhalten, ohne eine erneute Analyse durchzuführen. Übergeben Sie --no-reuse, um eine vollständige Neuanalyse zu erzwingen; dies ist nach einem Upgrade von Graft selbst empfehlenswert.

Der durch das Modell erstellte Teil verhält sich anders und ist der Bereich, in dem Fehler unbemerkt auftreten können. Zusammenfassungen und Kernpunkte werden zwischengespeichert. Jeder Knoten speichert einen Content-Hash seiner Quellen. Wenn sich eine Quelldatei ändert, wird der Knoten als veraltet markiert, anstatt als aktuell dargestellt zu werden. Dieses Flag hilft nur, wenn eine Aktion darauf erfolgt. Aktualisieren Sie mit graft build --deep, was erneut Modell-Token verbraucht.

Veraltung sichtbar machen:

graft check .
echo $?

In der fixierten Version 0.21.1 bedeutet der Exit-Status 0, dass der Graph mit dem Code übereinstimmt, und der Exit-Status 1 weist auf eine Abweichung hin. Ab Version 0.22 beendet graft check den Prozess bei einem Konflikt mit einem Team-Learning mit Status 1; das Gate für Abweichungen ist graft build --check. Ändern Sie daher den Befehl, wenn Sie die Version ändern. Führen Sie ihn über einen pre-push-Hook aus, damit eine sechs Monate alte Map keine verlässlichen Antworten zu Code liefert, der im März umgeschrieben wurde. Das README zu 0.21.1 beschreibt graft check als lokales Signal für Aktualität, und das aktuelle README führt build --check für CI auf. In jedem Fall wird graft/ von git ignoriert, sodass ein frischer CI-Checkout ohne Graphen startet, sofern der Job keinen erstellt.

Lesen Sie die veröffentlichten Benchmark-Zahlen sorgfältig

Das README zu 0.21.1 begann mit der Aussage „bis zu 4x günstiger und 3x schneller, bei besserer oder ohne Einbußen bei der Korrektheit“. Das aktuelle README lässt diese Zeile weg und beginnt mit kleineren Zahlen: „Über 162 Durchläufe desselben Agenten bei denselben Aufgaben: 32 % geringere Kosten, 42 % weniger nicht zwischengespeicherte Eingabe-Token, 60 % weniger Zeit und der gleiche Anteil an korrekten Antworten.“ Diese stammen aus den eigenen Benchmarks des Projekts, die im README veröffentlicht wurden. Hier sind die zwei Durchläufe, die vollständig berichtet werden.

DiagrammGraft's own published benchmark results, versus a no-map baseline, as of October 2026
Die Daten hinter diesem Diagramm
[
  {
    "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
  }
]

Der kontrollierte Sweep umfasst 162 Durchläufe über zwei Repositories, eines davon Graft selbst, mit drei Versuchen pro Aufgabe. Er berichtet von 42% weniger nicht zwischengespeicherten Eingabe-Token und 46% weniger Tool-Aufrufen. Der SWE-bench Verified-Durchlauf umfasst 50 Instanzen mit demselben Modell für beide Ansätze und berichtet von einer geringeren Einsparung: 23% der Token und 25% der Tool-Aufrufe. Ein dritter Durchlauf mit 15 PocketBase-Aufgaben, zehn Entwicklerfragen sowie fünf reproduzierten zusammengeführten Pull Requests kostete insgesamt 11,02 US-Dollar gegenüber 13,91 für die Baseline.

Betrachten Sie dies alles als Hersteller-Benchmark. Zwei Faktoren begrenzen die Aussagekraft. Der kontrollierte Sweep beinhaltet das eigene Repository von Graft, auf das die Autoren das Tool abgestimmt haben. SWE-bench Verified ist ein öffentlicher Datensatz mit Problemen aus bekannten Open-Source-Python-Projekten, und öffentliche Datensätze sind diejenigen, auf die Werkzeuge optimiert werden, ob beabsichtigt oder nicht. Keines davon ist eine Aussage über Ihr privates Monorepo, das seine eigenen Namenskonventionen und seinen eigenen toten Code hat.

Die Korrektheit verdient eine zweite Betrachtung. Beim kontrollierten Sweep gab es keine Veränderung: 93% mit der Map gegenüber 93% ohne. Der Sprung von 54% auf 66% tritt nur bei SWE-bench Verified auf. Ein Werkzeug, das Ihre Token-Kosten senkt und die Qualität gleich lässt, ist immer noch ein guter Tausch. Übertragen Sie nur nicht das SWE-bench-Ergebnis zur Korrektheit auf das Token-Ergebnis des Sweeps und zitieren Sie beides nicht als eine einzige Behauptung.

Messen Sie Ihre eigene Token-Differenz, bevor Sie irgendetwas davon glauben

Die einzige relevante Zahl stammt aus Ihrem Repository. Diese Methode dauert einen Nachmittag.

Wählen Sie eine Aufgabe, die Sie exakt wiederholen können. Eine Frage ist besser als eine Änderung, weil eine Änderung das Repository verändert und der zweite Durchlauf dann nicht mehr dasselbe Experiment ist. „Welches Modul erzwingt die Ratenbegrenzung für die Login-Route?“ hat die richtige Form.

Aktivieren Sie die Telemetrie und senden Sie sie an Ihr eigenes Terminal:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console
claude

Der Konsolenexporter gibt die Metrikdatensätze aus, sobald sie erfasst werden. Relevant ist claude_code.token.usage. Dieses Feld enthält ein Attribut type mit dem Wert input, output, cacheRead oder cacheCreation. Die Orientierung wird in input und cacheRead erfasst, weil dort die Dateiinhalte abgelegt werden. Addieren Sie diese beiden Werte.

Führen Sie die Aufgabe dreimal in jeweils einer neuen Sitzung aus, wobei die Map eingebunden ist. Entfernen Sie anschließend den Graft-Eintrag aus .mcp.json und führen Sie die Aufgabe noch dreimal aus. Vergleichen Sie die Mediane statt einzelner Durchläufe, weil Agent-Durchläufe stark schwanken und ein ungünstiger Durchlauf das Gegenteil der Wahrheit nahelegen kann. Erfassen Sie außerdem die Anzahl der Tool-Aufrufe: Tool-Aufrufe sind der Mechanismus und Tokens sind der Effekt. Eine Token-Einsparung ohne weniger Tool-Aufrufe bedeutet, dass sich etwas anderes verändert hat.

Ziehen Sie anschließend die Kosten ab, die der Benchmark nicht anzeigt. graft build --deep verbraucht bei jeder vollständigen Aktualisierung Model-Tokens. Die sechs Tool-Schemas werden bei jeder Anfrage mitgesendet. Wenn Ihre Agents auf einem gemieteten Server laufen, macht eine harte Obergrenze für Agent-Ausgaben daraus statt einer Überraschung ein Budget. Was die Telemetrie eines Coding-Agents tatsächlich meldet beschreibt außerdem, welche Daten den Rechner verlassen, sobald Sie den Exporter aktivieren.

Wann hilft eine Codebasis-Karte nicht mehr weiter?

  • Das Repository passt bereits in den Kontext. Ein einzelner kleiner Dienst benötigt keine Karte, und Sie bezahlen bei jeder Anfrage weiterhin für sechs Tool-Schemas. Wenn Ihr Agent heute jede Datei mit ein oder zwei Tool-Aufrufen findet, verzichten Sie darauf.
  • Ihre Sprache gehört zur breiten Kategorie. Generische Aufrufkanten können dazu führen, dass graft callers einen Aufrufer übersieht oder aufgrund einer Namenskollision einen falschen Aufrufer ermittelt. Bestätigen Sie das Ergebnis mit graft grep, bevor Sie den Änderungsumfang bewerten.
  • Der Graph ist veraltet, und niemand hat es bemerkt. Bei 0.21.1 beendet sich graft check bei Abweichungen mit Exit-Code 1; ab 0.22 gilt das für graft build --check. Das ist nur nützlich, wenn etwas den Befehl ausführt. Verwenden Sie dafür einen Pre-Push-Hook und verlassen Sie sich nicht auf manuelle Kontrollen.
  • Das Monorepo benötigt eine Eingrenzung. Ein einzelnes Git-Monorepo wird nicht aufgeteilt. graft build erkennt jedoch anhand von pnpm-workspace.yaml, package.json-Workspaces oder paketweisen go.mod, pyproject.toml oder Cargo.toml Teilprojekte und verwendet sie als Bereiche für das Ranking. Mit graft ask "..." --in services/billing/ schränken Sie eine Abfrage auf ein Teilprojekt ein. Derselbe Ansatz, der zu verschachtelten AGENTS.md-Dateien pro Paket führt, gilt auch für die Karte.
  • Der Agent ignoriert die Verdrahtung. Beobachten Sie die Tool-Aufrufe in einer realen Sitzung, bevor Sie daraus schließen, dass die Karte verwendet wird. Wenn ein Agent weiterhin grep ausführt, zeigt das, dass er die Regeldatei nie gelesen hat.

FAQ

Soll ich den Ordner graft/ in Git committen?

Nein. graft build fügt graft/ automatisch zu Ihrem .gitignore hinzu, weil der Graph wie node_modules ein regenerierbarer Cache ist. Er ändert sich bei fast jeder Bearbeitung. Dadurch werden echte Diffs unter Hunderten generierter Dateien verborgen. Committen Sie stattdessen die Verdrahtung, die Agents mitteilt, dass die Karte vorhanden ist, darunter AGENTS.md und .mcp.json. Lassen Sie jedes Teammitglied lokal graft build ausführen. Prüfen Sie dies mit grep -n graft .gitignore und git status --short vor Ihrem ersten Commit. Git verfolgt eine Datei weiter, sobald sie hinzugefügt wurde. Eine nachträgliche Bearbeitung von .gitignore hebt diese Nachverfolgung nicht auf.

Kostet der Betrieb von Graft Geld?

Die strukturelle Hälfte nicht. graft build, graft ask, graft check und die sechs MCP-Retrieval-Tools sind tree-sitter-Operationen. Sie rufen niemals ein Modell auf. graft build --deep ist der kostenpflichtige Teil. Damit werden die Klartextzusammenfassungen und die Cruxes pro Symbol über ein LLM geschrieben. Konfiguriert wird dies mit GRAFT_PROVIDER, GRAFT_API_KEY und GRAFT_MODEL, zusätzlich mit GRAFT_BASE_URL für jeden OpenAI-kompatiblen Endpunkt. Sie können Graft nur mit der Struktur ausführen. Für den Graphen selbst wird dann kein Token verbraucht.

Wie viel spart eine Codebase-Karte tatsächlich in meinem Repository?

Ohne Messung kann das niemand sagen. Das Projekt berichtet bei seinem eigenen Sweep mit 162 Durchläufen 42% weniger nicht gecachte Eingabetokens und bei SWE-bench Verified 23% weniger Tokens. Beide Werte beziehen sich auf eine Baseline ohne Karte. Beide sind Hersteller-Benchmarks. Einer davon wurde teilweise im eigenen Repository von Graft ausgeführt. Keiner beschreibt Ihren privaten Code. Führen Sie eine wiederholbare Frage dreimal mit Karte und dreimal ohne Karte aus. Setzen Sie dabei CLAUDE_CODE_ENABLE_TELEMETRY=1 und OTEL_METRICS_EXPORTER=console. Vergleichen Sie anschließend den Median von claude_code.token.usage für die Typen input und cacheRead.

Was geschieht mit dem Graphen bei einem Refactoring?

Die Struktur wird automatisch neu analysiert. Graft prüft den Arbeitsbaum und analysiert nur geänderte Dateien erneut. Daher wird eine Umbenennung bei der nächsten Abfrage erkannt. Wenn nichts verschoben wurde, dauert diese Prüfung in 0.21.1 ungefähr 3 ms und im aktuellen Release einige zehn Millisekunden. Nicht committete Änderungen werden ebenfalls erkannt, weil Graft Dateien statt der Git-Historie liest. Veraltet sind die vom Modell geschriebenen Zusammenfassungen. Jeder Knoten speichert einen Inhalts-Hash seiner Quellen. Eine geänderte Quelle markiert den Knoten als veraltet, statt ihn neu zu schreiben. Prüfen Sie auf Abweichungen (graft check . in 0.21.1, graft build --check ab 0.22). Führen Sie anschließend graft build --deep aus, um die geschriebene Hälfte zu aktualisieren.

Welche Coding-Agents können Graft heute verwenden?

In der festgelegten Version 0.21.1 bindet graft init Claude Code, Cursor, Codex, GitHub Copilot, Google Gemini, Kiro, Windsurf, Grok (xAI), AdaL, Hermes Agent und Google Antigravity ein, insgesamt elf Hosts. Im Changelog ist Hermes Agent seit 0.13.0 als First-Class-Host aufgeführt. hermes und antigravity sind in der festgelegten Version gewöhnliche --agents-IDs. Claude Code erhält die umfangreichste Integration: einen MCP-Server-Eintrag in .mcp.json, eine Statuszeile, Hooks nach der Bearbeitung und eine Skill-Datei unter .claude/. Codex erhält einen Abschnitt AGENTS.md sowie systemweite Einträge unter ~/.codex/. graft init --no-global überspringt diese Einträge. Grok erhält eine Skill-Datei und einen MCP-Block in .grok/config.toml. Hermes Agent und Antigravity lesen den Abschnitt AGENTS.md. Die übrigen Agents erhalten eine Rules- oder Steering-Datei. Jeder andere MCP-Client kann den Server direkt verwenden, indem er den Befehl npx -y @nanonets/graft@0.21.1 mcp registriert.

War dieser Artikel hilfreich?