Codegraph und Wissensdatenbank

Der Codegraph ist experimentell. Seine Oberfläche, sein Datenformat und sein Indizierungsverhalten können sich in späteren Versionen ändern.

Der Codegraph analysiert mit CodeGraph die Symbole eines Projekts und die Beziehungen zwischen ihnen. Die Sitzungswissensdatenbank speichert Entwurfsentscheidungen, Randbedingungen und gewonnene Erfahrungen. Codeverweise verbinden beides, sodass Sie sowohl die aktuelle Struktur des Codes als auch die Gründe dahinter sehen.

Seiten

Der Codegraph öffnet sich als Dialog mit den Tabs „Übersicht“, „Symbole“, „Code erkunden“ und „Dateien“. Seine Schaltfläche „Wissensdatenbank“ öffnet die Wissensdatenbank.

• Übersicht: die Anzahl der Dateien, Symbole und Beziehungen, die Verteilung der Sprachen und Symboltypen sowie der Synchronisierungsstatus („Automatische Synchronisierung aktiv“ oder „Vor Abfragen synchronisieren“). Ein Klick auf einen Eintrag der Verteilung zeigt die passenden Ergebnisse.
• Symbole: Suche nach Name oder Dateipfad („Symbole oder Dateipfade suchen…“). Die Seite eines Symbols zeigt seinen Quellcode mit Syntaxhervorhebung sowie „Eingehende Beziehungen“ und „Ausgehende Beziehungen“, gruppiert nach Beziehungsart und Datei. Beziehungen, die die Analyse abgeleitet hat, sind als „Abgeleitete Beziehung“ gekennzeichnet, und Zeilennummern springen zur Stelle des Aufrufs.
• Code erkunden: Beschreiben Sie eine Funktion oder einen Ablauf oder nennen Sie eine Datei oder ein Symbol, um den relevanten Quellcode und die zugehörigen Beziehungen zu sehen. Diese Abfrage läuft lokal und verwendet kein KI-Modell.
• Dateien: Blättern Sie durch die indizierten Dateien; ein Klick auf eine Datei listet ihre Symbole auf.
• Aufrufer und Aufgerufene Symbole: zeigen auf der Seite eines Symbols mehrere Aufrufebenen. Die „Suchtiefe“ beträgt standardmäßig 3 und höchstens 6. Es werden bis zu 500 Ergebnisse angezeigt; gibt es mehr, erscheinen die Gesamtzahl und ein Hinweis.
• Auswirkungsanalyse: zeigt auf der Seite eines Symbols die Symbole und Dateien, die von einer Änderung betroffen sein könnten, bis zur gewählten Tiefe (standardmäßig 3, höchstens 6). Es werden bis zu 500 Symbole und 2.000 Beziehungen angezeigt; wird das Ergebnis gekürzt, erscheinen die Gesamtzahl und ein Hinweis.
• Aufrufpfad: Suchen Sie auf der Seite eines Symbols nach einem Zielsymbol („Zielsymbol suchen…“), um den kürzesten Pfad entlang der Aufrufbeziehungen zu sehen. „Im Index wurde kein gerichteter Aufrufpfad gefunden.“ bedeutet nur, dass der Index keinen solchen Pfad enthält.

Das Arbeitsverzeichnis wechseln Sie über das Verzeichnismenü, das auch den vollständigen Pfad anzeigt. Seite, Frage in „Code erkunden“, Symbol, Tiefe, Ziel und Quellzeile sind Teil der URL, sodass Sie die Seite neu laden, in einem neuen Tab öffnen oder die Vor- und Zurück-Schaltflächen des Browsers verwenden können. Ein Link funktioniert auf demselben Backend mit einer gültigen Anmeldung.

Index für ein Projekt aktivieren

1. Klicken Sie in der Seitenleiste mit der rechten Maustaste auf ein Projekt oder eine Sammlung und wählen Sie „Experimentell“ → „Codegraph“.
2. Klicken Sie beim ersten Mal auf „CodeGraph herunterladen“. Das Backend, mit dem Sie verbunden sind, lädt die fest vorgegebene Version CodeGraph 1.6.0 von GitHub herunter und prüft sie anhand einer integrierten SHA-256-Prüfsumme („Die Prüfsumme des Downloads stimmt nicht überein. Die Laufzeit wurde nicht installiert.“ bedeutet, dass die Prüfung fehlgeschlagen ist). Eine separate Installation von Node.js ist nicht erforderlich.
3. Wählen Sie das „Arbeitsverzeichnis“ und klicken Sie auf „Indizierung aktivieren“. Das Projektverzeichnis und weitere Arbeitsverzeichnisse, die seine Sitzungen und Gruppen verwenden, werden getrennt aufgeführt; jeder Git-Worktree hat einen eigenen Index. Eine Sammlung benötigt mindestens eine Sitzung mit einem gültigen Arbeitsverzeichnis.
4. Warten Sie, bis der Status „Bereit“ lautet, und suchen Sie dann nach Symbolen oder Dateipfaden. Die Indizierung läuft im Hintergrund („Eine Indizierungsaufgabe läuft. Sie können diese Seite schließen oder die Indizierung deaktivieren, um die Aufgabe zu stoppen.“), und das Schließen der Seite bricht sie nicht ab.

„Synchronisieren“ aktualisiert den Index manuell oder versucht es nach einem Fehler erneut. Außerdem bringt VelaTerm den Index vor jeder Code-Abfrage auf den aktuellen Stand. Für dasselbe Backend und Arbeitsverzeichnis wird ein einziger Abfrageprozess wiederverwendet, der Dateiänderungen übernimmt, sobald sie geschehen, solange er läuft. Er beendet sich nach fünf Minuten ohne Abfragen; die nächste Abfrage öffnet den Index erneut und holt die Änderungen nach. Die Übersicht aktualisiert ihren Synchronisierungsstatus alle 30 Sekunden; ist die automatische Synchronisierung nicht verfügbar, synchronisiert VelaTerm trotzdem vor jeder Abfrage und gibt nie ein veraltetes Ergebnis als aktuell aus.

„Indizierung deaktivieren“ stoppt eine laufende Indizierungsaufgabe und behält die Indexdateien und die Verknüpfungen zu Wissenseinträgen, sodass Sie die Indizierung später wieder aktivieren können. Wird eine Aufgabe unterbrochen, wird sie innerhalb von etwa zwei Minuten als Fehler gemeldet, den Sie erneut versuchen können („Die vorherige Aufgabe wurde unterbrochen. Synchronisieren Sie, um sie erneut zu versuchen.“). Eine Indizierungsaufgabe darf höchstens 30 Minuten laufen.

Indizes werden in einem Ordner .codegraph/ im jeweiligen Arbeitsverzeichnis gespeichert und von CodeGraph verwaltet. VelaTerm führt die Indizierung selbst aus; es startet weder das Agenten-Installationsprogramm von CodeGraph, noch installiert es Git-Hooks. Ist das Projektverzeichnis ein Unterordner eines Repositorys, wird nur dieser Ordner indiziert.

Codebeziehungen anzeigen

Suchergebnisse zeigen Name, Typ und Ort jedes Symbols. Die Seite eines Symbols zeigt seinen Quellcode, eingehende und ausgehende Beziehungen sowie verknüpfte Wissenseinträge; klicken Sie auf ein benachbartes Symbol, um dort weiterzumachen.

Beziehungen stammen aus einer statischen Analyse und können unvollständig oder unsicher sein, worauf auch die Oberfläche hinweist („Die Beziehungen stammen aus einer statischen Analyse und können unvollständig oder unsicher sein.“); sie ersetzen nicht das Ausführen des Codes. Eine Symbolseite zeigt höchstens 200 Beziehungen pro Richtung und 600 Zeilen Quellcode, mit einem Hinweis, wenn es mehr gibt. Quelldateien über 4 MiB werden nicht angezeigt. Ändert sich eine Datei, während Sie sie ansehen, fordert VelaTerm Sie auf, erneut zu synchronisieren, bevor Sie sich auf ihre Zeilennummern verlassen.

Einträge verknüpfen und prüfen

Wählen Sie auf der Seite eines Symbols „Wissenseintrag verknüpfen“, wählen Sie einen vorhandenen Eintrag aus, vergleichen Sie seinen Text mit dem Code und speichern Sie. Auf der Seite des Eintrags führt „Codeverweise“ zurück zum Code, und die Eintragslinks im Codegraph öffnen den vollständigen Eintrag.

Eine Verknüpfung speichert Projekt, Arbeitsverzeichnis, Dateipfad, Symbolidentität und den SHA-256-Hashwert der Datei in der geprüften Fassung. Ändert sich die Datei, zeigt die Verknüpfung „Prüfung erforderlich“; lässt sich die Datei nicht mehr lesen oder wurde sie gelöscht, zeigt sie „Nicht verfügbar“; andernfalls zeigt sie „Unverändert“. Die Prüfung erfolgt dateiweise, sodass jede Änderung in derselben Datei eine erneute Prüfung erfordert. Eine geöffnete Eintragsseite prüft ihre Verweise regelmäßig.

Wählen Sie „Code und Eintrag prüfen“, um den aktuellen Code zu sehen, und „Prüfung bestätigen“, wenn der Eintrag weiterhin zutrifft. Das Backend prüft erneut, ob sich Datei und Eintrag in der Zwischenzeit geändert haben, und fordert Sie in diesem Fall zum Neuladen auf. Das Bestätigen aktualisiert nur den Codeverweis; der Text des Eintrags bleibt unverändert. Um die Schlussfolgerung zu ändern, bearbeiten Sie den Eintrag wie gewohnt.

Wird ein Symbol gelöscht oder umbenannt, geht die Verknüpfung nicht auf ein anderes Symbol mit demselben Namen über. Verwenden Sie „Verknüpfung entfernen“ und verknüpfen Sie das richtige Symbol. Das Löschen eines Eintrags entfernt seine Verknüpfungen; das Löschen eines Projekts entfernt dessen Indexeinträge und Verknüpfungen, aber weder andere Einträge noch die Indexdateien in den Arbeitsverzeichnissen.

Abfragen aus einer Sitzung

Jede Terminal- und Agentensitzung, die VelaTerm startet, verfügt über den Befehl vkb. Auch andere Agenten, die Terminalbefehle ausführen können, können ihn verwenden. Findet eine bestehende Sitzung vkb nach einem Update nicht, starten Sie die Sitzung neu.

Sind die „Vela Skills“ installiert (Einstellungen ▸ Allgemein), kann Claude /vkb und Codex $vkb verwenden. Der Skill wird nur ausgeführt, wenn Sie ausdrücklich darum bitten; Agenten rufen ihn nicht von sich aus während anderer Arbeiten auf. Listet ein Agent den Skill nach einem Update nicht auf, klicken Sie auf „Reinstall“ und starten Sie die Sitzung dieses Agenten neu.

vkb status
vkb explore "how a session is created and its working directory chosen"
vkb search "greet"
vkb node "<symbol ID from a search result>"
vkb callers "<symbol ID>" 2
vkb callees "<symbol ID>" 2
vkb impact "<symbol ID>" 3
vkb path "<start symbol ID>" "<end symbol ID>"
vkb files "src/session"
vkb memories "design decision"
vkb memory "<entry ID from a search result>"
vkb notes "reading notes"
vkb note <knowledge-base-ID> "folder/note.md"

• explore liefert dasselbe Ergebnis wie „Code erkunden“.
• callers, callees und impact akzeptieren eine optionale Tiefe; ihre Ergebnisse enthalten relations, total, depth und truncated.
• path erwartet zwei exakte Symbol-IDs aus Suchergebnissen, und files kann nach Pfad filtern.
• search liefert Code-Ergebnisse (nach Relevanz sortiert, mit hasMore, wenn es weitere gibt), Wissenseinträge und lokale Notizen getrennt.
• node liefert Quellcode, Beziehungen und verknüpfte Einträge eines Symbols.
• memories und memory durchsuchen und lesen Einträge der Sitzungswissensdatenbank, einschließlich Quellen, Versionen und Codeverweisen.
• notes und note durchsuchen und lesen lokale Wissensbasen (siehe Lokale Wissensbasen).

Code-Abfragen verwenden den Index des Verzeichnisses, in dem der Befehl ausgeführt wird. Ein Unterordner verwendet den Index seines Projekts, und ein verschachtelter separater Worktree greift nie auf den Index des Haupt-Checkouts zurück. Ist kein Index aktiviert oder schlägt eine Abfrage fehl, meldet das Ergebnis, dass Code nicht verfügbar ist; Wissensabfragen funktionieren weiterhin. Diese Befehle installieren nichts, aktivieren keine Indizierung und ändern keine Einträge.

Wo die Daten liegen

Die CodeGraph-Laufzeit wird in codegraph/1.6.0/ im Datenverzeichnis der Anwendung installiert. Indizierungsaufgaben und Verknüpfungen mit Einträgen werden in der Anwendungsdatenbank gespeichert (Tabellen knowledge_*). Die Indizierung läuft auf dem Backend, auf dem der Code liegt; Browser-Clients und SSH-Verbindungen lesen die Ergebnisse über ihre bestehende Verbindung, sodass kein zusätzlicher Port geöffnet wird. Jedes Backend hat eigene Indexeinstellungen und eine eigene Wissensdatenbank.

Telemetrie, Updateprüfungen und der separate Hintergrunddienst von CodeGraph sind deaktiviert. VelaTerm verwaltet den Abfrageprozess und kommuniziert mit ihm über einen privaten Kanal aus Standardeingabe und Standardausgabe, ohne einen Port zu öffnen. Die Indizierung selbst verwendet keine KI. Code oder Einträge, die ein Agent mit vkb liest, können an den konfigurierten Modelldienst dieses Agenten gesendet werden, genauso wie beim Lesen von Quelldateien durch den Agenten.

Ereignisse des Codegraphs werden in logs/runtime-*.log im Datenverzeichnis der Anwendung geschrieben. Ist VLX_LOG_DIR nicht gesetzt, legt VLX_KNOWLEDGE_LOG_DIR ihr Verzeichnis fest. VLX_KNOWLEDGE_LOG_LEVEL filtert sie (zum Beispiel error oder off). Das Protokoll enthält keinen Quellcode, keine Abfragetexte, keine Eintragstexte und keine Zugangsdaten.

CodeGraph wird unter github.com/colbymchenry/codegraph entwickelt und steht unter der MIT-Lizenz.