davidw-philips/cgraph

CodeGraph (codegraph)

codegraph erstellt und pflegt einen lokalen, automatisch synchronisierenden Wissensgraphen (SQLite) aller Symbole, Aufrufbeziehungen und Abhängigkeiten in einer Codebasis. Nach der Initialisierung kann Ihr Agent strukturelle Fragen direkt über das MCP-Tool codegraph_explore beantworten – in einem einzigen Aufruf, ohne Dateien lesen zu müssen – anstatt eine grep/read-Schleife zu verwenden.

Wann verwenden

• Beantworten von „Wie funktioniert X?“, „Wie gelangt X zu Y?“ oder Erkunden eines unbekannten Bereichs des aktiven Repositorys.
• Finden von Aufrufern/Aufgerufenen einer Funktion, Verfolgen von Aufrufpfaden oder Einschätzen der Auswirkungen einer Änderung.
• Starten, Verwalten oder Stoppen von CodeGraph-Hintergrund-Daemons und Umgebungsprozessen.
• Navigieren und Pflegen von Graph-Indizes über Git-Branches, Rebases und Git-Worktrees hinweg.
• Jede Frage, die Sie sonst durch Greppen oder Lesen mehrerer Dateien beantworten würden, um die Struktur manuell zu rekonstruieren.

NICHT verwenden für ein Repository ohne vorhandenen .codegraph/-Index (zuerst codegraph init ausführen) oder für externe/öffentliche Repositorys, die Sie nicht lokal indiziert haben – bevorzugen Sie für diese das deepwiki-Skill.

Vorab-Prüfung

command -v codegraph || Get-Command codegraph

Wenn fehlend, siehe INSTALL.md, oder direkt installieren mit:

# macOS / Linux – kein Node.js erforderlich, bündelt eigene Laufzeit
curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh

# Windows (PowerShell) – kein Node.js erforderlich
irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex

Dies ist für die meisten Umgebungen ausreichend – fahren Sie direkt mit Workflow & Start unten fort. Verwenden Sie die gebündelten scripts/ (siehe INSTALL.md) nur, wenn Sie speziell den npm-Installationspfad oder die Node-Bibliotheks-API von CodeGraph benötigen.

Workflow & Start

1. Einmalige Einrichtung pro Maschine

CodeGraph in diesen Agenten einbinden (bestätigt vor Änderungen):

codegraph install

2. Erstmalige Einrichtung pro Projekt

Graph für das aktive Projekt erstellen (erzeugt .codegraph/codegraph.db; führt vollständigen Anfangsindex durch):

cd your-project
codegraph init

3. Täglicher Start (bei Arbeitsbeginn)

Sie müssen nicht manuell einen Daemon oder Hintergrunddienst vor der Arbeit starten:

• Agent-Sitzungen (MCP) : Ihr KI-Host (VS Code Copilot, Claude Code, usw.) startet den MCP-Server automatisch über codegraph serve --mcp. Der Server verbindet sich bei Bedarf mit einem Hintergrund-Daemon oder startet einen solchen, komplett mit einem OS-Dateisystem-Überwacher.
• Gesundheitscheck : Führen Sie codegraph status aus, um die Index-Gesundheit, Symbol-/Kantenanzahlen und ausstehende Synchronisierungselemente zu überprüfen.
• Nachhol-Synchronisierung : Wenn Dateien geändert wurden, während der Agent geschlossen war (z. B. nach Pulls von Commits), führen Sie codegraph sync für ein sofortiges, schnelles inkrementelles Update aus.

4. Abfragen der Struktur

Ihr Agent ruft selbst das MCP-Tool codegraph_explore auf, sobald es eingebunden ist. Die gleiche Funktionalität ist auch in einer Shell verfügbar:

codegraph explore „wie gelangt X zu Y"
codegraph callers someFunction
codegraph callees someFunction
codegraph impact someSymbol

Umgebung & Daemon-Lebenszyklus

CodeGraph führt standardmäßig einen Hintergrund-Daemon („Daemon-Modus“) aus, sodass mehrere Client-Sitzungen einen gemeinsamen Überwacher, Cache und SQLite-Handle nutzen.

Daemons beenden

• Interaktives Beenden : Führen Sie codegraph daemon (oder codegraph daemons) aus. Wählen Sie den Projekt-Daemon (schwimmt nach oben) oder wählen Sie, alle Daemons zu beenden.
• Skriptgesteuertes / Nicht-interaktives Beenden : Daemons zeichnen ihre PID in <Projektstamm>/.codegraph/daemon.pid auf. Beenden Sie diese Prozess-ID direkt (oder überprüfen Sie ~/.codegraph/daemons/<hash>.json).
• Veraltete Sperren löschen : Wenn ein Prozess abstürzt oder abrupt beendet wird, löschen Sie veraltete Sperren und verwaiste Daemon-Artefakte mit:

  codegraph unlock
  

Umgebungsoptionen (Daemon & Überwacher)

• Direkter Modus (kein Daemon) : Setzen Sie CODEGRAPH_NO_DAEMON=1, um jede MCP- und CLI-Sitzung als unabhängigen, eigenständigen Prozess zu erzwingen, anstatt eine Verbindung zu einem gemeinsamen Daemon herzustellen.
• Dateiüberwacher deaktivieren : Setzen Sie CODEGRAPH_NO_WATCH=1 (oder verwenden Sie das --no-watch-Flag), um den Live-Dateisystem-Überwacher zu deaktivieren. Empfohlen auf langsamen Dateisystemen (WSL2 /mnt/-Laufwerke, Netzwerk-Mounts) oder bei batteriebetriebenen Setups.

Ausserbetriebnahme / Deinitialisieren

• Aus Projekt entfernen : Führen Sie codegraph uninit aus, um den .codegraph/-Index zu löschen und Git-Sync-Hooks zu entfernen (--force überspringt die Eingabeaufforderung).
• Von Maschine entfernen : Führen Sie codegraph uninstall aus (oder codegraph uninstall --keep-cli, um das CLI-Binary zu behalten).

Arbeiten mit Git-Branches & Worktrees

Git-Branch-Wechsel (Einzelner Arbeitsbaum)

• Dateisystembasierte Synchronisierung : CodeGraph verfolgt Dateipfade und Inhalts-Hashes in SQLite, nicht git status. Das Wechseln von Branches (git switch <branch> oder git checkout <branch>) ändert Dateien auf der Festplatte; der Dateiüberwacher erkennt Änderungen automatisch und synchronisiert den Index innerhalb von ~2 Sekunden inkrementell.
• Manuelle Synchronisierung : Wenn der Überwacher während des Checkouts deaktiviert oder inaktiv war, führen Sie codegraph sync für eine schnelle inkrementelle Nachholsynchronisierung aus.
• Große Rebases / Neuerstellungen : Nach einem massiven Rebase oder Branch-Merge mit vielen Konflikten erzwingen Sie eine saubere Index-Neuerstellung mit:

  codegraph index --force
  

• Git-Sync-Hooks (wenn Überwacher aus) : Wenn CODEGRAPH_NO_WATCH=1 gesetzt ist, kann CodeGraph post-commit-, post-merge- und post-checkout-Hooks installieren, die nach Branch-Wechseln automatisch im Hintergrund codegraph sync aufrufen.

Git-Worktrees und die Gefahr des „geliehenen Index“

• Index-Erkennung : CodeGraph findet .codegraph/, indem es von dem aktuellen Arbeitsverzeichnis aus die Elternverzeichnisse durchläuft.
• Die Gefahr : Bei Verwendung von Git-Worktrees (z. B. git worktree add ../feature-worktree feature), wenn dem Worktree ein eigenes .codegraph/-Verzeichnis fehlt, durchläuft CodeGraph die Verzeichnisse und bindet sich an den .codegraph/-Index des Haupt-Checkouts. Abfragen im Worktree geben Symbole und Quellcode vom Haupt-Checkout-Branch zurück und übersehen Worktree-spezifische Änderungen!
• Erkennung von Nichtübereinstimmungen : CodeGraph prüft detectWorktreeIndexMismatch, indem es git rev-parse --show-toplevel mit indexRoot über git rev-parse --git-common-dir vergleicht. Wenn ein Worktree den Hauptindex ausleiht, gibt CodeGraph Warnungen in codegraph status und MCP-Abfragetools aus.
• Die goldene Regel für Worktrees : Führen Sie immer codegraph init (oder codegraph init -i) in jedem Worktree-Verzeichnis aus. Jeder Worktree muss ein eigenes dediziertes .codegraph/-Verzeichnis haben, um seinen Branch unabhängig zu indizieren.
• Benutzerdefinierte Verzeichnisisolierung : Setzen Sie CODEGRAPH_DIR (z. B. export CODEGRAPH_DIR=.codegraph-worktree), wenn eine benutzerdefinierte Index-Ordnerbenennung oder Isolierung erforderlich ist (z. B. Trennung von Windows- und WSL2-Checkouts).

Regeln

• Vertrauen Sie den Ergebnissen des Graphen – er bleibt über einen Dateiüberwacher synchron (2-Sekunden-Entprellung nach einem Speichervorgang); nicht mit grep erneut überprüfen.
• Behandeln Sie den von codegraph_explore zurückgegebenen Quellcode als bereits gelesen; öffnen Sie dieselbe Datei nicht erneut mit dem Read-Tool.
• Fragen Sie nur ein Projekt ab, das einen .codegraph/-Index hat. Ein Pfad ohne einen solchen gibt eine klare Anweisung, stattdessen integrierte Tools zu verwenden – die Indexierung bleibt eine bewusste Entscheidung, kein Automatismus.
• Überprüfen Sie in Git-Worktrees mit codegraph status, ob der Worktree einen eigenen lokalen Index hat, anstatt den Index des Hauptbaums auszuleihen.
• Bevorzugen Sie codegraph_explore (oder codegraph explore von der CLI) gegenüber den spezialisierten versteckten Tools (codegraph_node, codegraph_search, codegraph_callers, codegraph_callees, codegraph_impact, codegraph_files, codegraph_status) – alles, was diese zurückgeben, ist bereits inline in codegraph_explore enthalten.

Siehe INSTALL.md für Installationsoptionen, einschließlich der gebündelten Node.js-Prüf-/Installationsskripte in scripts/, die nur für den npm-Installationspfad oder die Bibliothekseinbettung benötigt werden.