graphify in der Praxis: Jede Code-Bibliothek in ein durchsuchbares Wissensgraph-System verwandeln

Mittlerer Schwierigkeitsgrad | ca. 20 Minuten | Du lernst den vollständigen Workflow, mit graphify jede beliebige Code-Repository-Struktur in einen durchsuchbaren Wissensgraphen zu überführen – Schluss mit blindem Grep, hin zu strukturellem Code-Verständnis mit 71,5× Token-Komprimierung.

Projektüberblick

graphify ist ein Skill für ein KI-Coding-Assistenztool (skill), entwickelt von Safi Shamsi mit dem GitHub-Link safishamsi/graphify. Der Kern ist denkbar einfach: Jeden beliebigen Ordner (Code, Notizen, Papers, Bilder oder sogar Videos) in einen Abbild einer durchsuchbaren Wissensgraph-Struktur verdichten – sodass jedes Gespräch mit deinem KI-Assistenztool auf strukturiertem Wissen basiert, statt auf blindem Volltext-Matching.

Das Besondere sind drei Punkte:

• Multimodale Eingaben: Code (20 Sprachen), Dokumente, Bilder, PDFs sowie Audio-/Videoformate sind vollständig unterstützt und werden in denselben Graphen integriert
• Keine Embedding-Cluster: Mithilfe des Leiden-Community-Detection-Algorithmus wird direkt anhand der Graphtopologie geclustert – ohne Vektor-Datenbank und ohne separat ein Embedding-Modell laufen zu lassen
• Ehrliche Konfidenz: Jede Kantenbeziehung ist mit EXTRACTED / INFERRED / AMBIGUOUS annotiert – du weißt also, welche Beziehungen gefunden und welche nur abgeleitet sind

graphify kann als /graphify-Befehl in Claude Code, OpenClaw, Codex, Cursor, Trae und anderen gängigen KI-Coding-Assistenten genutzt werden. Außerdem lässt es sich über einen MCP Server oder als eigenständiger CLI-Aufruf verwenden.

Zielgruppe

Du hast mindestens ein mittelgroßes Projekt gebaut (mehr als tausend Zeilen Code) und arbeitest im Alltag mit Claude Code / OpenClaw / Codex oder anderen KI-Coding-Assistenten. Wenn du auf ein neues Code-Repository stößt, gibst du ihm normalerweise die Aufgabe, direkt den Quellcode zu lesen – aber mit der Dateizahl steigen Token-Verbrauch und das Problem der zersplitterten Kontextinformation immer deutlicher. Genau dieses Problem löst dieser Artikel.

Wichtige Abhängigkeiten und Umgebung

Vollständige Projektstruktur

my-project/
├── graphify-out/
│   ├── graph.json          # persistenter Wissensgraph, über Sitzungen hinweg abfragbar
│   ├── GRAPH_REPORT.md     # strukturierter Analysebericht (god nodes, unerwartete Verbindungen, empfohlene Fragen)
│   ├── graph.html          # interaktiver Graph (vis.js, im Browser direkt öffnen)
│   ├── cache/              # SHA256-Cache-Verzeichnis
│   └── transcripts/        # Audio-/Video-Transkriptionscache (nur wenn Video-Dependencies installiert sind)
├── .graphifyignore         # Ausschlussregeln (Syntax wie .gitignore)
└── .git/hooks/            # wird nach dem Hook-Install automatisch generiert

Schritt-für-Schritt-Anleitung

Schritt 1 — graphify installieren

graphify besteht aus zwei Teilen: zuerst das Python-Paket installieren, danach eine Plattform-Anpassungsschicht für deinen KI-Coding-Assistenten.

# Schritt 1: PyPI-Paket installieren
pip install graphifyy

# Schritt 2: Plattform-Anpassungsschicht installieren
# Beispiel: Für Claude Code

graphify install

# Für andere Plattformen: entsprechenden Befehl verwenden
# graphify install --platform codex
# graphify install --platform opencode
# graphify install --platform claw        # OpenClaw
# graphify install --platform aider
# graphify install --platform droid       # Factory Droid
# graphify install --platform trae
# graphify install --platform cursor
# graphify install --platform gemini

# Falls du unter Windows Probleme hast, Plattform explizit angeben

graphify install --platform windows

Nach der Installation erkennt dein KI-Coding-Assistent den Befehl /graphify.

Schritt 2 — Erster Lauf: Wissensgraph erzeugen

Wechsle in ein beliebiges Code-Verzeichnis, das du analysieren willst, und starte:

# Analyse des aktuellen Verzeichnisses
/graphify .

# Analyse eines bestimmten Verzeichnisses
/graphify ./src

# Analyse eines bestimmten Verzeichnisses und aktivierter aggressiverer Inferenzmodus
/graphify ./src --mode deep

# HTML-Visualisierung überspringen, nur Bericht und JSON erzeugen (schneller)
/graphify ./src --no-viz

graphify läuft in drei Schritten:

1. AST-Extraktion (ohne LLM) — Code-Dateien mit tree-sitter parsen und Klassen, Funktionen, Import-Beziehungen, Call-Graph, Docstrings sowie erklärende Kommentare extrahieren
2. Semantische Extraktion (LLM-Aufruf) — Dokumente, Papers, Bilder usw. über Claude auswerten und Konzepte, Beziehungen sowie Designmotive extrahieren
3. Graphaufbau & Clustering — alle Extraktionsergebnisse zusammenführen und mit dem Leiden-Community-Detection-Algorithmus clustern (basierend auf Kanten-Dichte, ohne embeddings)

Nach Abschluss erscheinen in graphify-out/ drei Artefakte:

ls graphify-out/
# graph.json  GRAPH_REPORT.md  graph.html  cache/

Schritt 3 — Nutzung der drei Artefakte verstehen

graphify-out/graph.json — persistenter Wissensgraph als Kernobjekt

Das ist der zentrale Baustein des Systems. Das Format ist ein standardmäßiger NetworkX-JSON-Export:

{
  "nodes": [
    {
      "id": "DigestAuth",
      "label": "DigestAuth",
      "source_file": "src/auth.py",
      "source_location": "L42",
      "community": "auth"
    }
  ],
  "edges": [
    {
      "source": "DigestAuth",
      "target": "Response",
      "relation": "imports",
      "confidence": "EXTRACTED",
      "confidence_score": 1.0
    },
    {
      "source": "Attention",
      "target": "Adam",
      "relation": "semantically_similar_to",
      "confidence": "INFERRED",
      "confidence_score": 0.87
    }
  ]
}

Jede Kante hat ein confidence-Label:

• EXTRACTED: Beziehung existiert direkt im Quellcode (Konfidenz 1.0)
• INFERRED: plausibel abgeleitete Beziehung, mit confidence_score (0.0–1.0)
• AMBIGUOUS: unklare Beziehung, wird im Bericht markiert, damit du sie manuell prüfen kannst

graphify-out/GRAPH_REPORT.md — strukturierter Analysebericht

Das ist eine Zusammenfassung für KI-Assistenztools und enthält:

• God Nodes: die wichtigsten Kernkonzepte mit der höchsten Knoten-Dichte (alle anderen Knoten müssen letztlich über sie laufen)
• Surprising Connections: überraschende Verbindungen über Dateien bzw. Typgrenzen hinweg, inklusive einer "Warum"-Erklärung
• Suggested Questions: 4–5 Fragen, die der Wissensgraph auf einzigartige Weise beantworten kann
• Design Rationale: Designmotive, aus Docstrings und Kommentaren extrahiert (# NOTE:, # WHY:, # HACK:)

graphify-out/graph.html — interaktiver Graph

Direkt im Browser öffnen: unterstützt Klick auf Knoten, Suche und Filter nach Community. Ideal fürs manuelle Erkunden der Code-Struktur.

Schritt 4 — Graph abfragen: drei Befehle

Ein Graph allein reicht nicht – er muss auch durchsuchbar sein. graphify bietet drei Abfragebefehle:

query — semantische Abfrage

# Am häufigsten: Knoten und Pfade finden, die mit der Frage zusammenhängen
graphify query "what connects Attention to the optimizer?"

# Token-Budget begrenzen
graphify query "show the auth flow" --budget 1500

# Mit DFS eine konkrete Route nachverfolgen (nicht zufälliges Sampling)
graphify query "what connects DigestAuth to Response?" --dfs

# Anderen Graph-Pfad als Standard verwenden
graphify query "..." --graph path/to/another-graph.json

Die Ausgabe enthält Knotenlabels, Kantentypen, Konfidenzen, Quell-Dateien und Quellpositionen. Du kannst diese Ausgabe direkt an dein KI-Assistenztool geben, damit es die Frage beantwortet:

Use this graph query output to answer the question. Prefer the graph
structure over guessing, and cite the source files when possible.

path — Pfad zwischen zwei Knoten finden

# vollständigen Pfad von Knoten A zu Knoten B verfolgen
graphify path "DigestAuth" "Response"

explain — Kontext für einen einzelnen Knoten erklären

# Nachbarn eines Knotens, Community und relevante Kanten anzeigen
graphify explain "SwinTransformer"

Schritt 5 — Always-On Hook integrieren (empfohlene Konfiguration)

Jedes Mal manuell /graphify einzutippen ist etwas mühsam. graphify unterstützt, die Graph-Kenntnisse automatisch in den Gesprächskontext deines KI-Assistenztools einzuspeisen – damit das Tool bei jeder Frage zuerst auf den Graphen schaut, statt blind in Dateien zu suchen.

Claude Code

graphify claude install

Dabei werden zwei Dinge gemacht: Zuerst wird eine Regel in CLAUDE.md geschrieben (damit Claude GRAPH_REPORT.md liest), und anschließend wird in settings.json ein PreToolUse hook installiert: vor jedem Glob- und Grep-Aufruf wird die Graph-Eingabeaufforderung injiziert:

graphify: Knowledge graph exists. Read GRAPH_REPORT.md for god nodes
and community structure before searching raw files.

OpenClaw / Aider / Trae usw.

Diese Plattformen unterstützen keine Tool-Hooks. Nutze stattdessen AGENTS.md:

graphify claw install   # OpenClaw
graphify aider install  # Aider
graphify trae install   # Trae

Cursor

graphify cursor install

Es wird .cursor/rules/graphify.mdc geschrieben und alwaysApply: true gesetzt. Cursor lädt den Inhalt dann automatisch in jedes Gespräch.

Deinstallation mit dem jeweiligen uninstall-Befehl:

graphify claude uninstall
graphify cursor uninstall
# ...

Schritt 6 — Inkrementelle Updates: nicht jedes Mal komplett neu aufbauen

Codebasen verändern sich täglich – ein vollständiger Rebuild dauert zu lange. graphify hat zwei Mechanismen für inkrementelle Updates:

--update: inkrementelle Extraktion basierend auf SHA256-Cache

# Nur geänderte Dateien verarbeiten, zusammenführen in den bestehenden Graphen
/graphify ./src --update

Im cache-Ordner wird pro Dateiinhalts-Hassch die Ergebnis-Zeit/Resultate gespeichert. graphify vergleicht Dateihashes und führt AST- und LLM-Extraktionen nur für die Dateien erneut aus, die sich verändert haben.

--watch: Änderungen automatisch überwachen

# Im Hintergrund laufen; wenn Code-Dateien gespeichert werden, wird AST sofort neu gebaut
/graphify ./src --watch

# Bei Änderungen an Dokumenten/Bildern wirst du gebeten, manuell einmal --update auszuführen

Der durch --watch ausgelöste Rebuild für Code ist reines AST und damit sehr schnell – kein LLM-Aufruf nötig. Für Dokument- und Bildänderungen ist weiterhin ein LLM nötig, daher benachrichtigt watch dich, dass du einmal manuell --update laufen lassen sollst.

Schritt 7 — git Hooks: Graph bei jedem Commit automatisch neu erstellen

Keine manuelle Ausführung und auch kein Hintergrundprozess? Dann delegiere den Graph-Rebuild an git:

graphify hook install

Dadurch werden in .git/hooks/ die Hooks post-commit und post-checkout hinterlegt. Bei jedem commit oder beim Wechsel des Branchs löst git automatisch einen Graph-Rebuild aus. Wenn der Rebuild fehlschlägt (z. B. AST-Parsefehler, LLM-Timeouts), bricht der Hook mit einem nicht-Null-Exitcode den git-Vorgang ab – damit gibt es kein stilles Versagen.

Status prüfen und Deinstallieren:

graphify hook status
graphify hook uninstall

Schritt 8 — Fortgeschrittene Nutzung

MCP Server: Graphen nativ durch KI verfügbar machen

Wenn dein KI-Assistent das MCP-Protokoll unterstützt, kann der Wissensgraph als MCP Tool freigegeben werden:

python -m graphify.serve graphify-out/graph.json

Die Ausgabe ist eine MCP-stdio-Konfiguration. Du musst sie nur in die MCP-Konfiguration deines KI-Assistenztools einfügen. Verfügbare Tools:

• query_graph: semantische Abfrage von Subgraphen
• get_node: Details zu einem Knoten abrufen
• get_neighbors: Nachbarn eines Knoten abrufen
• shortest_path: kürzesten Pfad zwischen zwei Knoten finden

Neo4j-Export

Möchtest du den Graphen in Neo4j importieren, um professionellere Graphanalysen zu machen?

# Cypher-Skript erzeugen (manuell importieren)
/graphify ./src --neo4j

# oder direkt in eine laufende Neo4j-Instanz pushen
/graphify ./src --neo4j-push bolt://localhost:7687

Wiki in Agent-lesbarem Format erzeugen

# Export als Markdown-Wiki, damit KI-Agenten über Dateien im Wissensspeicher navigieren
/graphify ./src --wiki

Erzeugt graphify-out/wiki/index.md (Einstiegspunkt) + je Community und je god node einen eigenen Markdown-Artikel.

Unterstützte Dateitypen im Überblick

Andere LLM-Anbieter festlegen

graphify nutzt standardmäßig das Modell, das auf deiner Plattform eingebettet ist (Claude Code verwendet Anthropic, Codex verwendet OpenAI). Wenn du ein anderes Modell erzwingen willst, kannst du dies per Umgebungsvariable konfigurieren (siehe die jeweils passende skill.md-Datei).

Häufige Probleme & Troubleshooting

1. Nach der Installation wird der graphify-Befehl nicht gefunden

Oft liegt das an einem Problem mit dem Python-Environment oder dem PATH:

# Installationsort des Pakets prüfen
pip show graphifyy

# Mit python -m aufrufen (ohne PATH-Abhängigkeit)
python -m graphify --help

# Oder per pipx isoliert installieren (empfohlen)
pip install pipx && pipx install graphifyy

2. Sehr wenige Graph-Knoten oder fast leer

Prüfe, ob .graphifyignore die Ziel-Dateien versehentlich ausschließt:

# Anzeigen, welche Dateien tatsächlich gescannt werden
/graphify ./src --no-viz  # mit --no-viz nur AST ausführen, kein LLM; schnell

# .graphifyignore-Syntax prüfen (wie .gitignore)
cat .graphifyignore

Auch möglich: Dateitypen sind nicht in der Support-Liste enthalten – stelle sicher, dass deine Code-Dateiendungen in der Tabelle „Unterstützte Dateitypen“ oben vorkommen.

3. LLM-Extraktionsphase läuft in Timeouts oder liefert API-Fehler

Netzwerkprobleme oder falsch konfigurierte API Keys:

# Prüfen, ob ein API Key existiert (Claude Code User sind meist automatisch konfiguriert)
# Nutzer anderer Plattformen prüfen die API Key-Umgebungsvariablen ihres jeweiligen Setups

# Mit --budget Token begrenzen, damit eine einzelne Anfrage nicht zu groß wird
/graphify ./src --budget 2000

# Nach Timeout überspringen erzwingen und mit anderen Dateien weitermachen (blockiert den gesamten Lauf nicht)

4. cache verursacht Inkonsistenz nach inkrementellem Update

SHA256-Cache ist beschädigt oder Dateien wurden extern geändert:

# Cache löschen, vollständigen Rebuild erzwingen
rm -rf graphify-out/cache
/graphify ./src

# Oder nur Cache für bestimmte Dateien löschen
rm graphify-out/cache/<entsprechender-hash>.json
/graphify ./src --update

5. Claude Code PreToolUse Hook greift nicht

Meist sind es Probleme mit dem Pfad oder dem Format der settings.json:

# Prüfen, ob Hooks erfolgreich geschrieben wurden
cat ~/.claude/settings.json | grep graphify

# Falls das Format vom IDE geändert wurde, den graphify-hook manuell nachtragen
# Siehe PreToolUse hook-Format in graphify skill.md

6. --watch meldet fehlendes watchdog

watchdog ist eine optionale Abhängigkeit:

pip install graphifyy[watch]

Weiterführende Lektüre / Weiterentwicklung

1. Custom Extractor: Support für neue Sprachen hinzufügen

Wenn dein Repo Sprachen nutzt, die graphify aktuell noch nicht unterstützt (z. B. Racket oder Nim), kannst du in extract.py eine neue Funktion extract_<lang> ergänzen. Diese soll sich am „Adding a new language extractor“-Teil in ARCHITECTURE.md orientieren. Der Ablauf ist klar: Funktion schreiben → Suffix registrieren → Abhängigkeiten hinzufügen → Tests schreiben.

2. GraphRAG Pipeline: Graphabfragen in ein RAG-System integrieren

der Kernwert von graphify liegt darin, dass du bei jeder Anfrage nicht erneut die Rohdateien lesen musst. Dadurch sinkt der Token-Verbrauch von O(n×Dateigröße) auf O(Größe des Subgraphen). In Kombination mit einer RAG Pipeline wird als Ansatz empfohlen:

import json

# 1. Zuerst mit GRAPH_REPORT.md auf High-Level-Intent schließen
# 2. Dann mit graphify query den relevanten Subgraphen ziehen
# 3. Den Subgraphen als Kontext an das LLM übergeben

with open("graphify-out/graph.json") as f:
    graph = json.load(f)

# graph["nodes"] und graph["edges"] sind der Kontext

3. Penpax: Das On-Device-Digital-Twin-Zukunftsbild des graphify-Autors

der langfristige Fahrplan von graphify ist Penpax – ein On-Device-Digital-Twin-Projekt. Es verknüpft Meeting-Notizen, Browser-History, Dateien, E-Mails und Code zu einem kontinuierlich aktualisierten Wissensgraphen, ohne Cloud und ohne Training deines Modells mit deinen Daten.

4. Multimodale Erweiterung: Video-Kurse zu einem Graphen machen

Wenn du technische Vorträge, Conference-Videos oder Podcast-Audio hast, kannst du sie mit der --video Dependency ebenfalls in den Wissensgraph einbinden:

pip install 'graphifyy[video]'
/graphify ./corpus --whisper-model medium

Whisper läuft lokal, und das Audio verlässt nie deine Maschine. Die Transkriptionen werden in graphify-out/transcripts/ gecacht; bei erneutem Ausführen wird direkt aus dem Cache gelesen.

5. Graph-Zusammenarbeit: Team teilt eine gemeinsame Wissensstruktur

die graphify-Artefakte (graph.json, GRAPH_REPORT.md) sind reiner Text und können ins git übernommen werden. Wenn Teammitglieder sie per pull holen, kann graphify hook install dieselbe Graphversion automatisch wiederverwenden. Das bedeutet: Architekturwissen ist versionierbar, im Code Review kann man Graphknoten referenzieren, und in PR-Beschreibungen können direkt god nodes zitiert werden. So hängt das Teamverständnis fortan nicht mehr davon ab, „wer wen fragt“.