graphify en pratique : transformer n’importe quel dépôt en graphe de connaissances interrogeable

Niveau intermédiaire | ~20 minutes | Vous allez maîtriser l’ensemble du flux de travail pour utiliser graphify et convertir n’importe quel dépôt de code en un graphe de connaissances interrogeable — et en finir avec le grep aveugle, grâce à une compréhension structurée du code avec un taux de compression de 71,5x Tokens.

Présentation du projet

graphify est une compétence d’assistant de codage IA (skill), développée par Safi Shamsi, disponible sur GitHub safishamsi/graphify. Son objectif est très simple : compresser n’importe quel dossier (code, notes, articles, images voire vidéos) en un seul graphe de connaissances interrogeable, afin que chaque conversation entre vous et votre assistant IA s’appuie sur des connaissances structurées plutôt que sur une recherche plein texte aveugle.

Ses points forts se résument à trois éléments :

• Entrée multi-modale : le code (20 langages), les documents, les images, les PDF et la vidéo/audio sont tous pris en charge — et convergent vers le même graphe
• Zéro clustering par embedding : utilisation de l’algorithme de détection de communautés Leiden, basé sur la topologie du graphe, sans base vectorielle, sans exécuter un modèle d’embedding séparément
• Confiance honnête : chaque arête de relation est annotée EXTRACTED / INFERRED / AMBIGUOUS — vous savez ce qui a été trouvé et ce qui a été déduit

graphify peut être utilisé via la commande /graphify de nombreux assistants de codage IA populaires (Claude Code, OpenClaw, Codex, Cursor, Trae, etc.), ou être appelé indépendamment via un serveur MCP ou une CLI.

Public visé

Vous avez déjà réalisé au moins un projet « moyen » (plus de mille lignes de code) et vous utilisez au quotidien Claude Code / OpenClaw / Codex (ou un autre assistant IA). Quand vous rencontrez une nouvelle base de code, vous avez l’habitude de la lui faire lire directement — mais plus il y a de fichiers, plus le coût en Tokens augmente, et plus la fragmentation du contexte devient évidente. Cet article sert précisément à résoudre ce problème.

Dépendances clés et environnement

Structure complète du projet

my-project/
├── graphify-out/
│   ├── graph.json          # Graphe de connaissances persistant, requêtable d’une session à l’autre
│   ├── GRAPH_REPORT.md     # Rapport d’analyse structuré (god nodes, connexions inattendues, questions suggérées)
│   ├── graph.html          # Graphe interactif (vis.js, ouverture directe dans le navigateur)
│   ├── cache/              # Répertoire de cache SHA256
│   └── transcripts/        # Cache des transcriptions audio/vidéo (nécessite l’installation de la dépendance video)
├── .graphifyignore         # Règles d’exclusion (syntaxe identique à .gitignore)
└── .graphify/hooks/            # généré automatiquement après l’installation du hook graphify

Étapes pas à pas

Étape 1 — Installer graphify

graphify se fait en deux temps : installer le paquet Python, puis installer la couche d’adaptation pour votre assistant de codage IA.

# Première étape : installer le paquet PyPI
pip install graphifyy

# Deuxième étape : installer la couche d’adaptation pour votre plateforme
# Exemple avec Claude Code :
graphify install

# Si vous utilisez une autre plateforme, remplacez par la commande correspondante :
# 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

# Si vous êtes sur Windows et rencontrez un problème, spécifiez explicitement la plateforme :
graphify install --platform windows

Une fois l’installation terminée, votre assistant de codage IA reconnaît la commande /graphify.

Étape 2 — Première exécution : générer le graphe de connaissances

Allez dans n’importe quel répertoire de code que vous souhaitez analyser, puis lancez :

# Analyser le répertoire courant
/graphify .

# Analyser un répertoire spécifique
/graphify ./src

# Analyser un répertoire spécifique et activer un mode de déduction plus agressif
/graphify ./src --mode deep

# Sauter la visualisation HTML : ne générer que le rapport et le JSON (plus rapide)
/graphify ./src --no-viz

graphify fonctionne en trois étapes :

1. Extraction AST (sans LLM) — utilisation de tree-sitter pour parser les fichiers de code et extraire les classes, fonctions, relations d’import, graphe d’appels, docstring et commentaires explicatifs
2. Extraction sémantique (appel LLM) — appel à Claude pour le contenu des documents, articles, images, etc., afin d’extraire les concepts, relations et motivations de conception
3. Construction du graphe et clustering — fusion de tous les résultats d’extraction, puis clustering via l’algorithme de communautés Leiden (basé sur la densité des arêtes, sans embeddings)

À la fin, trois artefacts apparaissent dans le répertoire graphify-out/ :

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

Étape 3 — Comprendre l’usage des trois artefacts

graphify-out/graph.json — le cœur persistant du graphe

C’est la pièce centrale du système. Le format est une exportation JSON standard compatible NetworkX :

{
  "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
    }
  ]
}

Chaque arête possède une balise confidence :

• EXTRACTED : relation directement présente dans le code source (confiance 1.0)
• INFERRED : déduction raisonnable, avec confidence_score (de 0.0 à 1.0)
• AMBIGUOUS : relation incertaine, signalée dans le rapport pour une validation humaine

graphify-out/GRAPH_REPORT.md — rapport d’analyse structuré

C’est un résumé destiné à l’assistant IA, incluant :

• God Nodes : concepts centraux ayant le plus grand degré (tous les autres nœuds doivent passer par eux)
• Surprising Connections : connexions transverses entre fichiers/types, inattendues, avec une explication « pourquoi »
• Suggested Questions : 4 à 5 questions que le graphe peut répondre de façon unique
• Design Rationale : motivations de conception extraites des docstrings et commentaires ( # NOTE: , # WHY: , # HACK: )

graphify-out/graph.html — graphe interactif

Ouvrez-le directement dans le navigateur : clic sur les nœuds, recherche, filtrage par communauté. Idéal pour explorer « à la main » la structure du code.

Étape 4 — Interroger le graphe : trois commandes

Un graphe seul ne suffit pas : il faut pouvoir le consulter. graphify fournit trois commandes de requête :

query — requête sémantique

# Le plus courant : trouver les nœuds et les chemins liés à la question
graphify query "what connects Attention to the optimizer?"

# Limiter le budget en Tokens
graphify query "show the auth flow" --budget 1500

# Utiliser DFS pour tracer un chemin précis (et non un échantillonnage aléatoire)
graphify query "what connects DigestAuth to Response?" --dfs

# Spécifier un chemin de graphe non par défaut
graphify query "..." --graph path/to/another-graph.json

La sortie inclut les étiquettes des nœuds, les types d’arêtes, la confiance, le fichier source et la position dans la source. Vous pouvez coller directement cette sortie à votre assistant IA pour qu’il réponde :

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

path — trouver un chemin entre deux nœuds

# Retracer le chemin complet du nœud A vers le nœud B
graphify path "DigestAuth" "Response"

explain — expliquer le contexte d’un nœud

# Afficher les voisins, la communauté, et les arêtes associées à un nœud
graphify explain "SwinTransformer"

Étape 5 — Intégration d’un Always-On Hook (recommandé)

À force de devoir taper manuellement /graphify, c’est vite pénible. graphify permet d’injecter automatiquement la connaissance du graphe dans le contexte de conversation de l’assistant IA, afin que, à chaque question, il privilégie le graphe plutôt que la recherche « à l’aveugle » dans les fichiers.

Claude Code

graphify claude install

Cela fait deux choses : écrire une règle dans CLAUDE.md (pour que Claude lise GRAPH_REPORT.md) ; puis installer un PreToolUse hook dans settings.json, afin d’injecter des instructions liées au graphe avant chaque appel à Glob et Grep :

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

OpenClaw / Aider / Trae, etc.

Ces plateformes ne supportent pas les hooks de tools : utilisez plutôt AGENTS.md :

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

Cursor

graphify cursor install

Écrire dans .cursor/rules/graphify.mdc puis définir alwaysApply: true : Cursor chargera automatiquement la règle dans chaque conversation.

Pour désinstaller, utilisez les commandes uninstall correspondantes :

graphify claude uninstall
graphify cursor uninstall
# ...

Étape 6 — Mises à jour incrémentales : ne plus reconstruire intégralement à chaque fois

Le dépôt change tous les jours : une reconstruction complète est trop lente. graphify propose deux mécanismes incrémentaux :

--update : extraction incrémentale basée sur le cache SHA256

# Ne traiter que les fichiers modifiés, et les fusionner dans le graphe existant
/graphify ./src --update

Dans le répertoire cache, le résultat précédent est enregistré via un hachage basé sur le contenu des fichiers. graphify compare les hashes : seuls les fichiers modifiés repassent par le pipeline AST et extraction LLM.

--watch : surveiller automatiquement les changements de fichiers

# Lancer en arrière-plan : reconstruction AST dès qu’un fichier de code est enregistré
/graphify ./src --watch

# Après modification de documents/images, il vous demandera d’exécuter manuellement --update

La reconstruction déclenchée par les changements de code via --watch n’est que de l’AST : elle est très rapide et ne nécessite pas d’appeler LLM. En revanche, les modifications de documents et d’images nécessitent une extraction via LLM : watch vous notifie donc d’exécuter une fois --update.

Étape 7 — Git Hooks : reconstruire le graphe à chaque commit

Vous ne voulez pas le lancer manuellement, et vous ne voulez pas non plus ouvrir un processus en arrière-plan ? Confiez la reconstruction du graphe à git :

graphify hook install

Cela écrit deux hooks dans .git/hooks/ : post-commit et post-checkout. À chaque commit ou changement de branche, git déclenche automatiquement la reconstruction du graphe. Si la reconstruction échoue (erreur d’analyse AST, timeout LLM, etc.), le hook interrompt l’opération git avec un code de sortie non nul, évitant ainsi l’échec silencieux.

Voir l’état et désinstaller :

graphify hook status
graphify hook uninstall

Étape 8 — Usages avancés

Serveur MCP : accès natif au graphe par l’IA

Si votre assistant IA supporte le protocole MCP, exposez le graphe comme un outil MCP :

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

La sortie produit une configuration MCP stdio : collez-la dans la configuration MCP de votre assistant IA. Les outils exposés incluent :

• query_graph : sous-graphe pour requêtes sémantiques
• get_node : récupérer les détails d’un nœud
• get_neighbors : récupérer les nœuds voisins
• shortest_path : trouver le plus court chemin entre deux nœuds

Export vers Neo4j

Souhaitez-vous importer le graphe dans Neo4j pour une analyse plus poussée ?

# Générer un script Cypher (import manuel)
/graphify ./src --neo4j

# Ou pousser directement vers une instance Neo4j en cours d’exécution
/graphify ./src --neo4j-push bolt://localhost:7687

Générer une Wiki lisible par des agents

# Exporter vers une wiki Markdown : les agents IA peuvent naviguer en lisant les fichiers
/graphify ./src --wiki

Génération de graphify-out/wiki/index.md (entrée) + un article Markdown pour chaque communauté et chaque god node.

Aperçu des types de fichiers pris en charge

Spécifier un autre fournisseur LLM

graphify utilise par défaut le modèle intégré à votre plateforme (Claude Code utilise Anthropic, Codex utilise OpenAI). Si vous voulez forcer un autre modèle, vous pouvez le définir via une variable d’environnement (voir le fichier correspondant skill.md).

Dépannage des problèmes fréquents

1. Après l’installation, la commande graphify introuvable

Généralement, c’est un problème d’environnement Python ou de PATH :

# Vérifier le lieu où le paquet est installé
pip show graphifyy

# Appeler via python -m (sans dépendre du PATH)
python -m graphify --help

# Ou installer isolé via pipx (recommandé)
pip install pipx && pipx install graphifyy

2. Trop peu de nœuds ou presque vides

Vérifiez si .graphifyignore exclut par erreur les fichiers ciblés :

# Voir quels fichiers graphify a réellement scannés
/graphify ./src --no-viz  # Avec --no-viz : seulement AST, pas de LLM, plus rapide

# Vérifier la syntaxe de .graphifyignore (identique à .gitignore)
cat .graphifyignore

Cela peut aussi venir du fait que vos fichiers ne sont pas dans la liste des types pris en charge : confirmez que vos extensions de code figurent dans le tableau « types de fichiers pris en charge » ci-dessus.

3. Timeout de l’étape d’extraction LLM ou erreur API

Problèmes réseau ou configuration de clé API :

# Vérifier que la clé API existe (les utilisateurs de Claude Code sont généralement configurés automatiquement)
# Pour les autres plateformes, vérifier la variable d’environnement de clé API correspondante

# Limiter les Tokens avec --budget pour éviter des requêtes trop lourdes
/graphify ./src --budget 2000

# En cas de timeout : forcer le skip et continuer sur les autres fichiers (ne bloque pas l’exécution globale)

4. cache : après mise à jour incrémentale, le graphe n’est pas cohérent

Cache SHA256 corrompu ou fichiers modifiés en externe :

# Effacer le cache et forcer une reconstruction complète
rm -rf graphify-out/cache
/graphify ./src

# Ou ne purger que le cache d’un fichier spécifique
rm graphify-out/cache/<hash-correspondant>.json
/graphify ./src --update

5. Le PreToolUse Hook de Claude Code ne s’active pas

Souvent, c’est un problème de chemin ou de format pour settings.json :

# Vérifier que les hooks ont bien été écrits
cat ~/.claude/settings.json | grep graphify

# Si l’IDE a modifié le format, complétez manuellement la section du hook graphify
# Référez-vous au format PreToolUse hook dans le fichier skill.md de graphify

6. --watch : erreur « watchdog manquant »

watchdog est une dépendance optionnelle :

pip install graphifyy[watch]

Lecture complémentaire / Pistes d’évolution

1. Personnaliser l’Extractor : ajouter la prise en charge d’un nouveau langage

Si votre base de code utilise un langage non encore supporté par graphify (par ex. Racket, Nim), vous pouvez ajouter une nouvelle fonction extract_<lang> dans extract.py. Elle doit parser l’AST via tree-sitter et suivre la section « Adding a new language extractor » d’ARCHITECTURE.md. Le flux est clair : écrire la fonction → enregistrer le suffixe → ajouter la dépendance → écrire des tests.

2. Pipeline GraphRAG : brancher les requêtes du graphe à un RAG

graphify a une valeur centrale : à chaque requête, il n’est pas nécessaire de relire les fichiers bruts ; la consommation de Tokens passe de O(n×taille du fichier) à O(taille du sous-graphe). Lors d’une intégration avec GraphRAG, l’approche recommandée est :

import json

# 1. Utiliser GRAPH_REPORT.md pour un jugement d’intention de haut niveau
# 2. Puis utiliser graphify query pour récupérer le sous-graphe pertinent
# 3. Donner le sous-graphe comme contexte au LLM

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

# graph["nodes"] et graph["edges"] correspondent au contexte

3. Penpax : la vision numérique jumelle côté terminal de l’auteur de graphify

dans le long terme, la feuille de route de graphify est Penpax — un projet de jumeau numérique côté terminal : il relie comptes-rendus de réunions, historique du navigateur, fichiers, emails et code en un graphe de connaissances mis à jour en continu, sans cloud et sans entraîner de modèle avec vos données.

4. Extension multi-modale : transformer des cours vidéo en graphe

Si vous avez des conférences techniques, des vidéos de conférences ou de l’audio de podcast, vous pouvez les intégrer au graphe via la dépendance --video :

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

Whisper s’exécute localement, et l’audio ne quitte jamais votre machine. Les transcriptions sont mises en cache dans graphify-out/transcripts/ ; un nouveau lancement lit directement le cache.

5. Collaboration de graphe : partager la structure des connaissances en équipe

t les artefacts de graphify (graph.json, GRAPH_REPORT.md) sont du texte pur : vous pouvez les committer dans git. Après que les membres de l’équipe les ont récupérés (pull), graphify hook install réutilise automatiquement la même version du graphe. Cela signifie que les connaissances d’architecture peuvent être versionnées ; lors des code reviews, on peut citer directement les nœuds du graphe, et même référencer les god nodes dans la description des PR. Ainsi, la compréhension de l’équipe n’est plus dépendante de « qui interroge qui ».