repo-graph

Strukturelles Graph-Gedächtnis für KI-Coding-Assistenten. Mappen Sie Ihre Codebasis. Navigieren Sie nach Struktur. Lesen Sie nur, was wichtig ist.

repo-graph gibt LLMs eine Karte Ihrer Codebasis – Entitäten, Beziehungen und Abläufe –, damit sie zu den richtigen Dateien navigieren können, ohne vorher alles lesen zu müssen.

Anstatt das Kontextfenster eines LLMs mit Ihrer gesamten Codebasis zu fluten (oder darauf zu hoffen, dass es richtig rät), erstellt repo-graph einen leichtgewichtigen Graphen dessen, was existiert, wie Dinge zusammenhängen und wo die Einstiegspunkte sind. Das LLM fragt den Graphen ab, findet die minimale Menge an benötigten Dateien und liest nur diese.

Demo

https://github.com/user-attachments/assets/a1e4171b-b225-40d4-9210-39453e14b76a

https://github.com/user-attachments/assets/fc3191e5-fc35-4bd7-8372-72af55995883

Der gleiche Fehler, das gleiche Modell, der gleiche Prompt – der einzige Unterschied ist, ob repo-graph installiert ist.

Die Aufgabe: Korrektur eines umgekehrten Vergleichsoperators in einem Go + Angular Monorepo (566 Knoten, 620 Kanten).

2,5x weniger Token. ~9x schneller. Die gleiche korrekte Korrektur.

Wie der Test durchgeführt wurde

Beide Durchläufe nutzten identische Bedingungen, um den Vergleich fair zu halten:

• Gleiches Modell: Claude Opus, 100% (kein Haiku-Routing)

• Gleicher Prompt: "Gruppen, die kürzlich erstellt wurden, werden als geschlossen angezeigt, und alte Gruppen als offen. Das ist verkehrt herum – neue Gruppen sollten für Mitglieder offen sein, um beizutreten. Finden und beheben Sie den Fehler."

• Frischer Kontext: Jeder Durchlauf startete bei /clear ohne vorherige Konversation

• Keine anderen Tools: CLAUDE.md, Plugins, Hooks und alle anderen MCP-Server wurden für beide Durchläufe entfernt – die einzige Variable war, ob repo-graph installiert war

• Keine Hinweise: Der Prompt beschreibt das Symptom, nicht den Ort – Claude muss group_controller.go:57 selbst finden

Ohne repo-graph sucht Claude mit grep nach Schlüsselwörtern, liest Dateien, sucht erneut, liest mehr Dateien und grenzt den Fehler schließlich ein. Mit repo-graph ruft Claude flow("groups") auf, erhält die exakte Handler-Funktion und Datei zurück, liest sie und behebt den Fehler.

Durchsuchen Sie vorab generierte Beispiele für FastAPI, Gin, Hono und NestJS – echte Graph-Ausgaben, die Sie inspizieren können, ohne etwas zu installieren.

Das Problem

LLMs, die mit Code arbeiten, verschwenden den Großteil ihres Kontexts mit der Orientierung:

• Lesen von Dateien, die sich als irrelevant herausstellen

• Übersehen von Verbindungen zwischen Komponenten in verschiedenen Sprachen

• Nicht wissen, wo ein Feature beginnt oder was es berührt

• Laden von 50 Dateien, wenn 5 ausreichen würden

Das ist teuer, langsam und wird schlimmer, je größer Codebasen werden.

Wie repo-graph es löst

repo-graph scannt Ihre Codebasis einmal und erstellt einen Graphen aus:

• Entitäten: Module, Pakete, Klassen, Funktionen, Routen, Services, Komponenten

• Beziehungen: Importe, Aufrufe, Handler, Definitionen, Enthaltenes

• Abläufe: End-to-End-Pfade vom Einstiegspunkt bis zur Datenebene

Anschließend stellt es 12 MCP-Tools bereit, die dem LLM Folgendes ermöglichen:

1. Orientierung – "Welche Sprachen sind in diesem Repo? Was sind die Hauptfunktionen?"

2. Navigation – "Verfolge den Login-Ablauf von der Route bis zur Datenbank" / "Was ist der kürzeste Pfad zwischen UserService und der Zahlungs-API?"

3. Eingrenzung – "Wie viele Zeilen müsste ich lesen, um dieses Feature zu verstehen?" / "Gib mir nur die Dateien, die ich für diesen Bugfix brauche"

4. Bewertung – "Was ist der Wirkungsbereich einer Änderung an dieser Funktion?" / "Welche Dateien sind die größten Wartungsrisiken?"

Das LLM erhält strukturellen Kontext in wenigen hundert Token, anstatt tausende Zeilen zu lesen.

Unterstützte Sprachen

Mehrere Analysatoren können auf ein Repo passen (z. B. Go-Backend + Angular-Frontend + SCSS). Jeder trägt seine Knoten und Kanten zu einem einzigen, vereinheitlichten Graphen bei.

Installation

pip install mcp-repo-graph

Erfordert Python 3.11+. Einzige Laufzeitabhängigkeit: mcp[cli].

Schnellstart

1. Den Graphen generieren

repo-graph-generate --repo /path/to/your/project

Dies scannt die Codebasis und schreibt Graph-Daten in .ai/repo-graph/ innerhalb des Ziel-Repos.

2. Mit Ihrem KI-Assistenten verbinden

Fügen Sie dies zu Ihrer MCP-Konfiguration hinzu:

Claude Code (~/.claude/claude_code_config.json oder Projekt .mcp.json):

{
  "mcpServers": {
    "repo-graph": {
      "command": "repo-graph",
      "args": ["--repo", "/path/to/your/project"]
    }
  }
}

Mit Umgebungsvariable:

{
  "mcpServers": {
    "repo-graph": {
      "command": "repo-graph",
      "env": { "REPO_GRAPH_REPO": "/path/to/your/project" }
    }
  }
}

3. Verwendung

Der KI-Assistent hat nun Zugriff auf alle 12 Tools. Beispielabfragen, die er beantworten kann:

• "Was macht diese Codebasis?" -> status Tool

• "Verfolge den Checkout-Ablauf" -> flow Tool

• "Was würde kaputtgehen, wenn ich UserService ändere?" -> impact Tool

• "Welche Dateien brauche ich für diesen Fehler?" -> minimal_read Tool

• "Diese Datei ist zu groß, wie sollte ich sie aufteilen?" -> split_plan Tool

• "Zeig mir den Auth-Ablauf visuell" -> graph_view Tool

4. Mit einem Git-Hook aktuell halten (empfohlen)

Fügen Sie repo-graph-generate zu einem Pre-Commit-Hook hinzu, damit der Graph automatisch auf dem neuesten Stand bleibt – kein LLM-Kontext wird für die Neugenerierung verbraucht:

# .git/hooks/pre-commit (or add to your existing hook)
#!/bin/sh
repo-graph-generate --repo .
git add .ai/repo-graph/

chmod +x .git/hooks/pre-commit

Jeder Commit hält den Graphen aktuell. Das LLM hat immer eine frische Karte, ohne ein einziges Token für generate zu verschwenden.

Tipp: Wenn Sie keine Graph-Daten in der Versionskontrolle haben möchten, fügen Sie .ai/repo-graph/ zu .gitignore hinzu und überspringen Sie die git add-Zeile – der Graph lebt dann nur lokal.

Referenz der MCP-Tools

Generierung

Navigation

Kontext-Budgetierung

Gesundheitsanalyse

Funktionsweise

1. Erkennen — scan_project_dirs() findet Projektwurzeln (einschließlich Monorepo-Layouts wie packages/*, apps/*, services/*, src/*). Jeder Analysator prüft auf seine Marker-Dateien.

2. Scannen — passende Analysatoren extrahieren Entitäten und Beziehungen mithilfe von Regex-Heuristiken. Kein AST-Parsing, keine externen Toolchains, kein Build-Schritt erforderlich.

3. Zusammenführen — alle Analysator-Ergebnisse werden zu einem einzigen Graphen zusammengeführt. Knoten werden nach ID dedupliziert, Kanten nach (von, zu, Typ).

4. Bereitstellen — der MCP-Server lädt den Graphen in den Arbeitsspeicher und stellt BFS-basierte Traversierungs-Tools bereit.

Graph-Datenformat

Generierte Dateien liegen in .ai/repo-graph/ innerhalb des Ziel-Repos:

• nodes.json — [{id, type, name, file_path}, ...]

• edges.json — [{from, to, type}, ...]

• flows/*.yaml — benannte Feature-Abläufe mit geordneten Schrittsequenzen

• state.md — menschenlesbarer Schnappschuss zur schnellen Orientierung

Kanten-Typen: imports, defines, contains, uses, calls, handles, handled_by, exports, includes.

Einen neuen Analysator hinzufügen

Erstellen Sie repo_graph/analyzers/<sprache>.py:

from .base import AnalysisResult, Edge, LanguageAnalyzer, Node, scan_project_dirs, rel_path, read_safe

class MyLangAnalyzer(LanguageAnalyzer):

    @staticmethod
    def detect(repo_root):
        # Check for language marker files
        return any(
            (d / "my-marker").exists()
            for d in scan_project_dirs(repo_root)
        )

    def scan(self):
        nodes, edges = [], []
        # ... scan files, extract entities, build relationships ...
        return AnalysisResult(
            nodes=nodes,
            edges=edges,
            state_sections={"MyLang": f"{len(nodes)} entities\n"},
        )

    # Optional: file-level analysis for bloat_report / split_plan
    def supported_extensions(self):
        return {".mylang"}

    def analyze_file(self, file_path):
        # Return dict with function/method sizes, class counts, etc.
        pass

    def format_bloat_report(self, analysis):
        # Format the analysis dict into a human-readable string
        pass

Registrieren Sie ihn in analyzers/__init__.py, indem Sie ihn zu _analyzer_classes() hinzufügen.

Lizenz

MIT

Support

Wenn repo-graph Ihnen Zeit gespart hat, ziehen Sie in Betracht, mir einen Kaffee auszugeben.