Code zoeken met de codegraph

Deze gids laat zien hoe je een repo in de codegraph krijgt en hem daarna gebruikt om de vraag te beantwoorden die je vóór een refactor echt hebt: wat hangt hiervan af?

De codegraph is een database van symbolen en randen, opgebouwd door je geregistreerde checkouts met tree-sitter te parsen. De tools zijn op agenten gericht — je bereikt ze door het een agent te vragen.

Voordat je begint

De codegraph indexeert Dart, JavaScript, TypeScript, TSX, PHP, Python, Rust, Zig, C, C++, Go, Java, Ruby, C#, Swift, Kotlin, R, Assembly, MATLAB en Ada. Bestanden in een andere taal worden niet geparseerd en komen dus niet voor in search_code, code_symbol, code_callers, code_callees of code_impact.

Nog twee dingen bepalen wat er wordt geïndexeerd:

In een git-worktree laat de enumeratie zich leiden door git ls-files --cached --others --exclude-standard, dus elk .gitignore, genest ignore-bestand, .git/info/exclude en het globale excludes-bestand wordt gerespecteerd. Dat houdt node_modules en builduitvoer uit de codegraph.
Gegenereerde Dart wordt hoe dan ook overgeslagen. Gegenereerde bestanden worden meestal gecommit, dus git alleen zou ze niet uitsluiten en ze veranderen bij elke codegen-run.

Een repo laten indexeren

Het registreren van een checkout activeert RepoAdded, wat automatisch de pipeline index_code start. Zie Repos toevoegen aan een werkruimte.

Om handmatig opnieuw te indexeren:

Open Instellingen → Werkruimte → Repository’s.
Klik op de knop Code indexeren in de rij van de repo.
Terwijl hij draait toont de knop het aantal gedane bestanden van het totaal, met een annuleerknop. Als hij klaar is, verandert hij in een vinkje met het aantal symbolen.

De codegraph is opgedeeld per werkruimte, repo en checkout: de gekoppelde checkout is één partitie, en elke worktree van een ruimte krijgt zijn eigen partitie (met de id van zijn geïsoleerde repo als sleutel).

Twee begrenzingen zijn het kennen waard, want ze verklaren een wachttijd die op een hang lijkt:

De bestandswatcher laat op de host maar één indexering tegelijk toe — een tweede checkout wacht. De pipeline index_code is apart beperkt tot één run per werkruimte, dus twee repo’s in dezelfde werkruimte komen in de wachtrij; verschillende werkruimtes kunnen parallel indexeren. De indexeerder zelf serialiseert twee runs van dezelfde checkout, zodat een pipelinestart en een watchersweep hem niet dubbel kunnen parsen.
Worktrees van slapende ruimtes (geen bericht in de afgelopen week) worden noch gevolgd noch geïndexeerd. Gekoppelde checkouts blijven gevolgd. Een beslissing om over te slaan wordt na vijf minuten opnieuw bekeken, dus een ruimte die weer actief wordt, wordt opgepakt.

Een symbool vinden

Vraag een agent om te zoeken. De tool is search_code en heeft zowel een werkruimte als een repo nodig:

search_code(workspace_id: "...", repo_id: "...", query: "authentication middleware")

Repo-id’s komen uit list_repos. Het optionele argument mode is keyword, semantic of hybrid en staat standaard op hybrid — BM25 over namen, signaturen en doc-commentaar, samengevoegd met vectorsimilariteit.

Elk resultaat bevat de id, naam, gekwalificeerde naam, soort, bestandspad, begin- en eindregel van het symbool, en zijn signatuur als die er is. De id is het handvat dat je aan elke andere tool op deze pagina geeft.

Als je de exacte naam kent, kun je hem in plaats daarvan direct opzoeken:

code_symbol(workspace_id: "...", repo_id: "...", name: "MyClass")

Aanroepen traceren

Beide nemen een symbol_id uit een zoekresultaat, plus een optionele limit (standaard 50):

code_callers(workspace_id: "...", symbol_id: "...")
code_callees(workspace_id: "...", symbol_id: "...")

code_callers geeft de symbolen terug met een inkomende rand naar dit symbool; code_callees geeft degene terug waarvan het afhangt.

Controleren wat een wijziging zou breken

Dit is de tool waarvoor deze hele pagina bestaat:

code_impact(workspace_id: "...", symbol_id: "...", depth: 3)

Hij berekent de reverse-dependencyradius: alles wat direct of transitief van het symbool afhangt via calls-, extends- en implements-randen (imports, mixes-in en generieke verwijzingen worden in de codegraph opgeslagen, maar hier niet doorlopen). depth is het maximale aantal hops, tussen 1 en 6, met 2 als standaard.

Het resultaat bestaat uit drie velden:

root — het symbool waar je naar vroeg
impacted — de bereikbare verzameling, inclusief de root op depth 0, elk met hun depth vanaf de root
edgeCount — hoeveel randen de traversal overstak, als aantal en niet als de randen zelf

Draai hem voordat je iets hernoemt of een signatuur wijzigt, en geef de agent de impacted-lijst als zijn scope.

Resultaten worden gecontroleerd tegen de werkkopie van de aanroeper zelf

Voor een agent als aanroeper wordt de ruimte-id automatisch geïnjecteerd en worden resultaten geverifieerd tegen de werkkopie van die ruimte. Een symbool waarvan het bestand niet meer bestaat in de boom van de aanroeper, wordt weggelaten en het antwoord bevat een staleOmitted-telling plus een opmerking dat de index voor die symbolen verouderd is.

Daarom kunnen jij en een agent verschillende antwoorden krijgen op dezelfde query, en daarom kan een agent in de ene ruimte een ander antwoord krijgen dan een agent in een andere. Elk gesprek in een ruimte deelt die ene worktree. Verificatie faalt open: een verouderd antwoord heeft de voorkeur boven een leeg antwoord.

Vraag een agent om code_impact (of review_studio.blastRadius) te draaien als je de blast radius van een wijziging wilt weten. Zie Review-compute.

Semantisch zoeken heeft het embeddingmodel nodig

Symbolen en feiten worden op het moment van schrijven geëmbed en alleen als het embeddingmodel op het apparaat is geïnstalleerd. Tot dan hebben mode: "semantic" en de semantische helft van hybrid niets om tegen te matchen en is zoeken in de praktijk alleen op trefwoorden gebaseerd.

Installeer het model via Instellingen → Server → Diagnose en privacy → Semantisch zoeken voordat je indexeert. Symbolen krijgen een vector zodra hun bestand wordt ingelezen.

Let ook op dat elke herbouw van de serverbinary de grammatica-dylibs opnieuw klaarzet en hun mtimes wijzigt, wat elk indexcontrolepunt ongeldig maakt en bij de volgende run één volledige herwandeling van elke checkout afdwingt. Hij herhasht wel, maar extraheert ongewijzigde bestanden niet opnieuw.

Wat er in de codegraph zit

Soorten symbolen: function, method, class, field, enum, constructor, getter, setter, typedef, extension, mixin, variable.

Soorten randen: calls, imports, extends, implements, mixes in, references.

De canonieke signaturen voor deze tools staan in MCP-tools.

Gerelateerde gidsen

Gerelateerde concepten

Werkruimtes en isolatie