Graphify — un graphe de connaissances pour les assistants de code

1📖 Glossaire — le vocabulaire de base

• AST (Abstract Syntax Tree) — représentation arborescente du code produite par un parseur, sans exécuter le code.
• tree-sitter — parseur incrémental multi-langages (20+ langages) ; extrait classes / fonctions / imports localement, sans appel LLM.
• NetworkX — lib Python de graphes ; sert de structure de stockage du graphe en mémoire.
• Leiden (clustering) — algorithme de détection de communautés ; regroupe les nœuds fortement liés en clusters thématiques, par densité d'arêtes (pas d'embeddings).
• God node — le nœud le plus connecté ; le hub par lequel tout passe.
• Surprising connection — arête entre deux entités de fichiers / modules différents, classée par degré d'inattendu.
• Rationale node — un commentaire # WHY:, une docstring ou une décision de design extraite comme nœud, relié au code qu'il explique (rationale_for).
• Confidence tag — étiquette portée par chaque relation : EXTRACTED (vue dans le code), INFERRED (déduite par le LLM), AMBIGUOUS (incertaine).
• MCP (Model Context Protocol) — protocole qui expose des outils à un agent ; Graphify peut servir le graphe via un serveur MCP (serve.py).

2Comment ça marche — le pipeline

Graphify enchaîne deux passes (AST local, puis sémantique LLM) puis clusterise le résultat.

flowchart LR
    SRC[Repo<br/>code, docs, PDF, images] --> P1[Pass 1<br/>tree-sitter AST<br/>local, 0 token]
    P1 --> P2[Pass 2<br/>extraction sémantique<br/>LLM, optionnelle]
    P1 --> G[NetworkX graph<br/>+ clustering Leiden]
    P2 --> G
    G --> OUT1[graph.json<br/>requêtable]
    G --> OUT2[GRAPH_REPORT.md<br/>god nodes, connexions]
    G --> OUT3[graph.html<br/>visu interactive]

• Passe 1 — AST via tree-sitter. Déterministe, locale, 20+ langages. Extrait classes, fonctions, imports, call graphs, docstrings, commentaires de rationale. Aucun appel LLM, aucun octet de code n'est envoyé.
• Passe 2 — extraction sémantique. Uniquement pour docs / markdown / PDF / images (et transcription audio/vidéo via Whisper). Seule étape qui appelle un modèle. Désactivable avec --code-only.
• Clustering Leiden. Détecte les communautés par densité d'arêtes → regroupe le graphe en modules cohérents. Pas de vector store.
• Confidence tags. Chaque arête est marquée EXTRACTED / INFERRED / AMBIGUOUS.

3À quoi ressemble le graphe

graph.html est une visu force-directed interactive : chaque nœud est une entité, la couleur encode la communauté Leiden, la taille encode le degré (les gros = god nodes). On clique un nœud, on filtre par communauté, on cherche.

Rendu réel de graph.html : les clusters de couleurs sont les communautés Leiden, les gros nœuds les god nodes. (source : aieatingtheworld.com)

Le rapport GRAPH_REPORT.md en extrait le signal :

• God nodes — les concepts par lesquels tout passe.
• Connexions surprenantes — liens cross-fichiers / cross-modules, classés par degré d'inattendu, chacun avec un pourquoi en clair.
• Rationale nodes — docstrings, # NOTE: / # WHY:, décisions de design, rattachés au code via des arêtes rationale_for.
• Questions suggérées — 4-5 questions que le graphe répond particulièrement bien.
• Confidence tags — ce qui a été trouvé vs deviné.

4Installation et init

Deux étapes, une seule fois. Prérequis : Python 3.10+, et de préférence uv (ou pipx).

# Étape 1 — le moteur (package PyPI : graphifyy, double y)
uv tool install graphifyy

# Étape 2 — enregistrer le skill /graphify auprès de l'assistant
graphify install            # Claude Code par défaut ; --platform pour les autres

Puis, dans le repo : /graphify .

Extras à la demande (le cœur est code-only) : graphifyy[pdf], [office] (.docx/.xlsx), [video] (transcription), [mcp] (serveur MCP), [all].

Ce qu'il ignore. Un .graphifyignore (syntaxe .gitignore) à la racine. Le .gitignore est respecté automatiquement et les deux sont fusionnés — .graphifyignore exclut davantage, jamais ne réinclut ce que git exclut.

5Enregistrer le skill par IA

Le skill expose le slash command /graphify (build) et une couche « always-on » qui pousse l'assistant à préférer le graphe pour les questions de code (voir §6). Certaines plateformes bundlent les deux.

Forme générique pour les ~20 plateformes : graphify install --platform <nom>.

Global vs projet

• Global (défaut) — enregistre le skill dans ton profil → /graphify partout. Cas normal.
• Projet (--project) — écrit le skill dans le repo (.claude/skills/… ou .agents/skills/…), pour le commit et le partager à l'équipe.

Le graphe, lui, est toujours par repo (graphify-out/). Pas de graphe « global » multi-repos sauf dossier parent commun.

6Utilisation

À la main (CLI)

/graphify .                     # construit le graphe du dossier courant
/graphify . --code-only         # AST seul, 0 appel LLM (run rapide)
/graphify ./docs --update       # re-extrait uniquement les fichiers changés
/graphify --watch               # rebuild auto en tâche de fond quand le code change

graphify query "comment l'auth parle à la base ?"   # BFS — contexte large (défaut)
graphify query "..." --dfs                           # DFS — trace un chemin précis
graphify query "..." --budget 1500                   # plafonne la réponse à N tokens
graphify path "AuthModule" "Database"                # plus court chemin entre 2 concepts
graphify explain "RateLimiter"                       # explication en clair d'un nœud
graphify export callflow-html                        # page d'archi Mermaid
graphify add https://arxiv.org/abs/1706.03762        # ajoute un doc au graphe

Via l'IA (le mode normal)

C'est l'intérêt réel. Après graphify <plateforme> install, une section est écrite dans le fichier d'instructions de l'assistant (CLAUDE.md, AGENTS.md, .cursor/rules/…) qui lui dit de consulter le graphe avant de répondre aux questions de code, et de le reconstruire après un changement. Tu ne tapes plus graphify query toi-même — tu poses ta question en langage naturel, l'agent lance la requête en arrière-plan.

Sur Claude Code et Gemini CLI, un hook PreToolUse intercepte les appels Glob / Grep (et sur Claude Code, les Read fichier par fichier) et redirige vers GRAPH_REPORT.md / graphify query avant que l'agent parte lire l'arbre brut.

Échange typique — tu ne mentionnes jamais Graphify :

Toi : « pourquoi le rate-limiter touche la base directement ? »
IA  : (lance graphify query en arrière-plan, lit un sous-graphe borné)
    → « RateLimiter → DbPool via checkQuota(). La rationale attachée
       (# WHY:) indique que le cache a été retiré pour la cohérence forte. »

(Re)construire reste aussi en langage naturel : « indexe ce repo » → l'agent lance /graphify . ; « réindexe les docs » → /graphify --update. Au premier build, le skill colle dans le chat les 3 sections clés du rapport (god nodes, surprises, questions suggérées) et propose d'explorer.

7L'économie de tokens

C'est le payoff de l'usage via l'IA (§6). Sans graphe, répondre à « comment l'auth parle à la base ? » force l'agent à grep puis lire des dizaines de fichiers en série — chaque lecture consomme des tokens. Avec le graphe, la même question déclenche une requête bornée qui renvoie un petit sous-graphe (quelques centaines de tokens) au lieu du contenu brut.

sequenceDiagram
    participant Dev as Développeur
    participant AI as Assistant
    participant G as graphify-out/graph.json
    Dev->>AI: "Comment l'auth parle à la base ?"
    Note over AI: sans graphe → lit N fichiers en série (coûteux)
    AI->>G: graphify query "..."
    G-->>AI: sous-graphe borné (quelques nœuds)
    AI-->>Dev: réponse ancrée sur l'archi réelle

Chiffres annoncés par le projet : sur un corpus mixte de 52 fichiers (~92k mots), une requête coûte en moyenne ~1,7k tokens contre ~123k en lecture brute — soit 71,5× moins. À plus grande échelle (~500k mots), une requête BFS reste ~2k tokens contre ~670k. Le ratio tient parce qu'une requête renvoie un sous-graphe borné, quasi indépendamment de la taille du repo.

8Exemple de bout en bout

Scénario : tu débarques sur un repo que tu ne connais pas — ici le corpus httpx fourni par Graphify (une couche transport HTTP, 6 fichiers Python). Objectif : le comprendre sans lire les 6 fichiers un par un.

1 — Installer + enregistrer (une seule fois sur la machine)

uv tool install graphifyy
graphify install          # skill /graphify + couche always-on (Claude Code par défaut)

2 — Construire le graphe

cd httpx
/graphify .

Graphify parse le code en AST (local), passe le LLM sur les docstrings et docs, puis clusterise. Sortie dans graphify-out/ : 144 nœuds, 330 arêtes, 6 communautés. Le build de ce corpus est quasi instantané ; sur un gros repo, c'est là que le temps se passe (surtout la passe sémantique).

3 — Lire ce que l'agent te renvoie

Le skill ne te jette pas le graph.json brut : il colle dans le chat 3 sections de GRAPH_REPORT.md, celles qui donnent une prise immédiate —

• God nodes : Client, AsyncClient, Response, Request — les 4 classes dont tout dépend. Tu sais par où entrer dans le code.
• Connexion surprenante : DigestAuth → Response — l'auth digest lit la réponse pour rejouer la requête signée sur un 401. Un couplage invisible à la simple lecture linéaire.
• Questions suggérées : 4-5 pistes que le graphe est bien placé pour répondre.

…puis il te propose d'explorer.

4 — Explorer en langage naturel

Tu ne tapes pas graphify query — tu discutes, l'agent interroge le graphe pour toi (mécanique du §6) :

Toi : « comment une requête passe du Client au réseau ? »
IA  → Client.send() → _transport → HTTPTransport.handle_request()
       (chemin tracé sur le graphe — pas les 6 fichiers relus)

Besoin d'un lien précis entre deux points ? « trace le chemin entre DigestAuth et Response » → l'agent lance un path sous le capot et te rend les sauts intermédiaires.

5 — Modifier le code, garder le graphe frais

Tu ajoutes un RetryTransport. Au git commit, le hook rebuild l'AST : le nouveau nœud et ses arêtes apparaissent dans le graphe, 0 coût API (c'est de l'AST local).

graphify hook install     # une seule fois — ensuite automatique à chaque commit

Si tu avais touché un README ou un doc, il faudrait un /graphify . --update en fin de session pour relancer la passe LLM sur ces fichiers (voir §9 — les deux vitesses).

9Garder le graphe à jour

Le point le plus négligé — un graphe périmé ment. Deux vitesses de mise à jour à ne pas confondre :

• Au commit (automatique, AST-only). Le post-commit hook (graphify hook install) rebuild la structure du code (fichiers changés uniquement), instantanément, 0 coût API. callflow-html régénéré. Il ne relance pas la passe sémantique.
• À la fin (manuel, --update). Pour ré-extraire les docs / markdown / images modifiés (passe LLM), il faut lancer /graphify . --update. Le hook te le signale quand des docs ont bougé.

sequenceDiagram
    participant Dev as Développeur
    participant Hook as post-commit hook
    participant AST as Graphify · AST local
    participant Sem as Passe sémantique · LLM
    participant Out as graphify-out/

    Dev->>Dev: édite code + docs
    Dev->>Hook: git commit
    Hook->>AST: rebuild incrémental (fichiers changés)
    AST->>Out: graph.json + callflow-html à jour (structure)
    Note over AST,Sem: le hook ne lance PAS la passe sémantique
    AST-->>Dev: signale « docs/images changés → --update »
    Note over Dev: en fin de session, si des docs ont bougé
    Dev->>Sem: /graphify . --update
    Sem->>Out: nœuds docs / rationale ré-extraits (LLM)
    Dev->>Out: git add graphify-out/ (si commité pour l'équipe)

Les garde-fous qui rendent ça sûr :

1. Incrémental partout. --update comme le hook ne retouchent que les fichiers changés (cache SHA256). Markdown : cache frontmatter-aware — changer tags: seul n'invalide rien.
2. Merge driver. graphify hook install installe aussi un git merge driver : graph.json est union-mergé quand deux devs commitent en parallèle — jamais de conflict markers.
3. Après un refactor. Fichiers supprimés → « ghost nodes » persistants. --force (ou GRAPHIFY_FORCE=1) écrase même si le nouveau graphe a moins de nœuds.
4. --watch (optionnel) — process de fond qui rebuild l'AST à chaque sauvegarde ; utile en workflow multi-agents où plusieurs agents écrivent en parallèle.

En équipe. graphify-out/ est fait pour être commité : une personne build + commit, les autres pull et leur assistant lit le graphe direct. manifest.json (chemins relatifs) → portable, pas de rebuild complet au premier checkout.

10Graphe vs RAG vectoriel — quand l'utiliser

Quand le choisir :

• ✅ Gros codebase / monorepo, onboarding sur un repo inconnu, questions d'architecture cross-modules, tracé d'un chemin entre deux modules distants.
• ❌ Petit repo ou question ciblée sur un fichier déjà connu → overkill, un grep suffit. Graphify cartographie ce qui existe, il ne range pas un code spaghetti.

Notes liées

• outiller-developpement-ia-skills-agents-instructions — la vue d'ensemble des leviers de contexte pour une IA de code ; Graphify y est l'exemple de « graphe de code », OpenSpec celui de « spec versionnée ».
• mcp-model-context-protocol — le protocole via lequel Graphify peut aussi exposer son graphe à un agent (serve.py).

Sources

• GitHub — safishamsi/graphify — repo officiel : commandes par plateforme, extras, hooks, team setup, MCP server
• graphify.net — pipeline, chiffres (71,5×), corpus d'exemple httpx, comparaison Sourcegraph/Code2Vec/Neo4j
• Knowledge Graphs for AI Coding Assistants (graphify.net) — pourquoi le graphe bat le RAG vectoriel, PreToolUse hook
• Quick Start — reduce token usage (rajeevpentyala.com) — POC Copilot CLI, piège du scan-path --project
• Graphify + code-review-graph (DEV.to) — hooks, garde-fous ressources, requête graphify query
• How I Used Graphify with GitHub Copilot (Medium) — retour d'usage concret côté Copilot
• OpenSpec (Fission-AI) — exemple de workflow spec-driven cité en §9 (propose / apply / archive)