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 (25 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).
• _origin — champ porté par chaque nœud de graph.json : ast s'il vient du parseur local, autre valeur s'il vient de la passe sémantique. C'est le seul juge fiable de ce que contient réellement le graphe (voir §9).
• MCP (Model Context Protocol) — protocole qui expose des outils à un agent ; Graphify peut servir le graphe via un serveur MCP (exécutable graphify-mcp, installé avec le package).

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, 25 langages (dont les relations extends/implements Java). Extrait classes, fonctions, imports, call graphs, docstrings, commentaires de rationale. Les schémas SQL sont aussi AST-extraits sans LLM : tables, FK, jointures (extra [sql]). Aucun appel LLM, aucun octet de code n'est envoyé.
• Passe 2 — extraction sémantique. Uniquement pour docs / markdown / YAML / 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 et regroupe le graphe en communautés cohérentes. Pas de vector store. ⚠ Ces communautés reflètent des concepts et des couches (mapping, controllers, gestion d'erreurs…), pas les modules de build : sur un multi-module, elles traversent les frontières Maven/Gradle. C'est une information, pas un défaut : cela révèle le couplage réel.
• 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), [sql] (schémas SQL dans le graphe), [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 il ne réinclut ce que git exclut. Le flag --no-gitignore désactive l'héritage git si du code utile vit sous .gitignore.

Règles utiles :

• Négations internes : elles fonctionnent dans le .graphifyignore, avec la sémantique git des patterns (* reste dans un segment, ** traverse). Pour n'indexer qu'un sous-arbre d'un répertoire exclu, la forme canonique est :

dir/*
!dir/sous-arbre
!dir/sous-arbre/**
# puis ré-exclusions fines dans le sous-arbre

• Wrappers de build (mvnw, gradlew…) : à exclure d'office. Purs scripts shell, ils ne créent que du bruit dans le graphe.
• .claude/ et les dossiers d'outillage agent : en install projet (§5), le SKILL.md de graphify fait 38 Ko et ses fiches references/ portent le total à ~100 Ko — le tout dans le corpus. Constaté : 62 nœuds parasites du type « Step 1 - Ensure graphify is installed » au milieu du graphe applicatif. Exclure .claude/ d'office, idem .agents/ et .github/skills/. Le graphe n'a rien à apprendre de sa propre documentation.
• Lockfiles et gros JSON générés (pnpm-lock.yaml, snapshots de migrations, fichiers de traduction) : ce sont des cibles de la passe sémantique (YAML/JSON), donc du coût LLM pur pour zéro valeur structurelle. Un pnpm-lock.yaml pèse facilement 500 Ko.

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 affected "RateLimiter"                      # traversée inverse : ce qui casse si on y touche
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. Par défaut c'est un nudge, une suggestion que le modèle peut ignorer. Sur Claude Code, graphify install --project --strict installe la variante bloquante : la première lecture brute de la session est refusée avec redirection vers graphify query, puis le hook retombe en nudge. Jamais plus d'un blocage par session ; GRAPHIFY_HOOK_STRICT=1/0 bascule sans réinstaller.

É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. La commande graphify benchmark [graph.json] rejoue cette mesure sur son propre graphe.

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). graphify hook install pose un post-commit et un post-checkout (réalignement du graphe au changement de branche). Rebuild de la structure du code uniquement (fichiers changés), 0 coût API, en tâche de fond détachée : le commit rend la main immédiatement (log dans ~/.cache/graphify-rebuild.log), avec skip auto pendant rebase, merge et cherry-pick. 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/ (artefacts portables uniquement)

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. Il a deux moitiés : l'entrée dans .gitattributes (à commiter) et la définition dans .git/config (locale). Comme .git/hooks/ n'est jamais versionné, chaque clone relance graphify hook install une fois (idempotent, marqueurs graphify-hook-start/end). À documenter dans le README du repo.
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. Même chose après avoir durci le .graphifyignore : le rebuild affiche fail-closed: kept N node(s) … that left the scan corpus but still exist on disk et conserve les nœuds nouvellement exclus tant qu'on ne force pas.
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 : commiter le graphe, PAS l'état local. Seuls graph.json, GRAPH_REPORT.md et graph.html sont portables (chemins relatifs). Tout le reste de graphify-out/ est de l'état machine-local en chemins absolus (/Users/<name>/…) : manifest.json (cache de détection), cache/, les fichiers .graphify_*, cost.json, les snapshots datés AAAA-MM-JJ/. Poser un .gitignore dans graphify-out/ :

manifest.json
cache/
.graphify_*
cost.json
20*/

Trois choses à savoir :

• ces fichiers se régénèrent seuls au premier build de chaque machine : les ignorer ne fait rien perdre
• contrôle avant chaque commit du graphe : grep -rl "$HOME" graphify-out/ --exclude-dir=cache doit sortir vide (hors .graphify_*)
• une personne build + commit, les autres pull : leur assistant lit le graphe direct, sans rien installer. L'install (moteur + hook) ne conditionne que la mise à jour du graphe, pas sa lecture.

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 (graphify-mcp).

Sources

• GitHub — safishamsi/graphify — repo officiel : commandes par plateforme, extras, hooks, team setup, MCP server
• Changelog Graphify — releases détaillées : hook --strict, portabilité des chemins (fin des fuites username), sémantique des patterns ignore, écritures atomiques
• 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
• GitHub — rhanka/graphify — le fork TypeScript (@sentropic/graphify sur npm) : crédite l'upstream, étend vers ontologies configurables et réconciliation d'entités
• 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)