davidw-philips/cgraph

CodeGraph (codegraph)

codegraph construit et maintient un graphe de connaissance local (SQLite) auto-synchronisé de chaque symbole, arête d'appel et dépendance dans une base de code. Une fois initialisé, votre agent répond aux questions structurelles directement depuis le graphe via l'outil MCP codegraph_explore — en un seul appel, sans aucune lecture de fichier — au lieu d'une boucle de grep/lecture.

Quand l'utiliser

• Répondre à "Comment fonctionne X ?", "Comment X atteint-il Y ?", ou explorer une zone inconnue du dépôt actif.
• Trouver les appelants/appelés d'une fonction, tracer les chemins d'appel, ou évaluer le rayon d'impact d'un changement.
• Démarrer, gérer, ou arrêter les démons d'arrière-plan et les processus d'environnement CodeGraph.
• Naviguer et maintenir les index du graphe entre branches Git, rebases et worktrees Git.
• Toute question à laquelle vous répondriez sinon en grepant ou en lisant plusieurs fichiers pour reconstruire la structure manuellement.

Ne PAS l'utiliser pour un dépôt n'ayant pas encore d'index .codegraph/ (exécutez d'abord codegraph init) ou pour des dépôts externes/publics que vous n'avez pas encore indexés localement — préférez la compétence deepwiki pour ceux-ci.

Vérification préalable

command -v codegraph || Get-Command codegraph

Si manquant, voir INSTALL.md, ou installez directement avec :

# macOS / Linux — pas besoin de Node.js, il intègre son propre exécuteur
curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh

# Windows (PowerShell) — pas besoin de Node.js
irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex

C'est tout ce dont la plupart des environnements ont besoin — passez directement à Workflow & Démarrage ci-dessous. N'utilisez les scripts/ fournis (voir INSTALL.md) que si vous avez spécifiquement besoin du chemin d'installation npm ou de l'API de bibliothèque Node de CodeGraph.

Workflow & Démarrage

1. Configuration unique par machine

Connectez CodeGraph à cet agent (confirme avant de modifier quoi que ce soit) :

codegraph install

2. Configuration initiale par projet

Construisez le graphe pour le projet actif (crée .codegraph/codegraph.db ; exécute l'index initial complet) :

cd votre-projet
codegraph init

3. Démarrage quotidien (Au début du travail)

Vous n'avez pas besoin de lancer manuellement un démon ou un service d'arrière-plan avant de travailler :

• Sessions Agent (MCP) : Votre hôte IA (VS Code Copilot, Claude Code, etc.) démarre automatiquement le serveur MCP via codegraph serve --mcp. Le serveur se connecte ou génère un démon d'arrière-plan à la demande, complet avec un observateur de système de fichiers OS.
• Vérifier l'état : Exécutez codegraph status pour vérifier la santé de l'index, les compteurs de symboles/arêtes, et les éléments de synchronisation en attente.
• Synchronisation de rattrapage : Si des fichiers ont changé pendant que l'agent était fermé (par exemple, après un pull de commits), exécutez codegraph sync pour une mise à jour rapide et incrémentielle.

4. Interroger la structure

Votre agent appelle lui-même l'outil MCP codegraph_explore une fois connecté. La même fonctionnalité est disponible depuis un shell :

codegraph explore "comment X atteint Y"
codegraph callers uneFonction
codegraph callees uneFonction
codegraph impact unSymbole

Cycle de vie de l'Environnement & du Démon

CodeGraph exécute un démon d'arrière-plan (mode démon) par défaut afin que plusieurs sessions client partagent un seul observateur, cache et gestionnaire SQLite.

Arrêter les démons

• Arrêt interactif : Exécutez codegraph daemon (ou codegraph daemons). Sélectionnez le démon du projet (remonte en haut) ou choisissez d'arrêter tous les démons.
• Arrêt scripté / non interactif : Les démons enregistrent leur PID dans <racine_projet>/.codegraph/daemon.pid. Terminez cet ID de processus directement (ou inspectez ~/.codegraph/daemons/<hash>.json).
• Nettoyage des verrous obsolètes : Si un processus plante ou est terminé brusquement, nettoyez les verrous obsolètes et les artefacts orphelins de démon avec :

  codegraph unlock
  

Bascules d'environnement (Démon & Observateur)

• Mode direct (Pas de démon) : Définissez CODEGRAPH_NO_DAEMON=1 pour forcer chaque session MCP et CLI à s'exécuter comme un processus indépendant et autonome plutôt que de se connecter à un démon partagé.
• Désactiver l'observateur de fichiers : Définissez CODEGRAPH_NO_WATCH=1 (ou utilisez le drapeau --no-watch) pour désactiver l'observateur de système de fichiers en direct. Recommandé sur les systèmes de fichiers lents (lecteurs WSL2 /mnt/, montages réseau) ou les configurations à batterie limitée.

Désaffectation / Désinitialisation

• Supprimer du projet : Exécutez codegraph uninit pour supprimer l'index .codegraph/ et les hooks de synchronisation Git (--force ignore l'invite).
• Supprimer de la machine : Exécutez codegraph uninstall (ou codegraph uninstall --keep-cli pour conserver le binaire CLI).

Travailler avec les branches Git & les worktrees

Changement de branche Git (Arbre de travail unique)

• Synchronisation basée sur le système de fichiers : CodeGraph suit les chemins de fichiers et les hachages de contenu dans SQLite, pas git status. Changer de branche (git switch <branche> ou git checkout <branche>) modifie les fichiers sur disque ; l'observateur de fichiers détecte automatiquement les changements et synchronise l'index de manière incrémentielle en environ 2 secondes.
• Synchronisation manuelle : Si l'observateur a été désactivé ou inactif pendant l'extraction (checkout), exécutez codegraph sync pour un rattrapage incrémentiel rapide.
• Rebases majeurs / Reconstructions : Après un rebase massif ou une fusion de branche avec de lourds conflits, forcez une reconstruction propre de l'index avec :

  codegraph index --force
  

• Hooks de synchronisation Git (Quand l'observateur est désactivé) : Si CODEGRAPH_NO_WATCH=1 est défini, CodeGraph peut installer des hooks post-commit, post-merge et post-checkout qui invoquent automatiquement codegraph sync en arrière-plan après les changements de branche.

Worktrees Git & Le risque d'"Index Emprunté"

• Découverte de l'index : CodeGraph découvre .codegraph/ en remontant les répertoires parents à partir du répertoire de travail courant.
• Le risque : Lors de l'utilisation de worktrees Git (par exemple git worktree add ../feature-worktree feature), si le worktree manque de son propre répertoire .codegraph/, CodeGraph remonte et se lie à l'index .codegraph/ de la branche principale. Les requêtes dans le worktree renverront les symboles et le code source de la branche de l'extraction principale, manquant les changements spécifiques au worktree !
• Détection d'inadéquation : CodeGraph vérifie detectWorktreeIndexMismatch en comparant git rev-parse --show-toplevel avec indexRoot via git rev-parse --git-common-dir. Lorsqu'un worktree emprunte l'index principal, CodeGraph émet des avertissements dans codegraph status et les outils de requête MCP.
• La règle d'or pour les worktrees : Exécutez toujours codegraph init (ou codegraph init -i) dans chaque répertoire de worktree. Chaque worktree doit avoir son propre répertoire .codegraph/ dédié pour indexer sa branche de manière indépendante.
• Isolation par répertoire personnalisé : Définissez CODEGRAPH_DIR (par exemple export CODEGRAPH_DIR=.codegraph-worktree) si un nommage ou une isolation d'index personnalisé est nécessaire (par exemple séparer les extractions Windows et WSL2).

Règles

• Faites confiance aux résultats du graphe — il reste synchronisé via un observateur de fichiers (anti-rebond de 2 secondes après une sauvegarde) ; ne revérifiez pas avec grep.
• Considérez le code source retourné par codegraph_explore comme déjà lu ; ne rouvrez pas le même fichier avec l'outil de lecture.
• N'interrogez qu'un projet possédant un index .codegraph/. Un chemin sans cela renvoie des conseils clairs pour utiliser les outils intégrés à la place — l'indexation reste une décision délibérée, pas automatique.
• Dans les worktrees Git, vérifiez avec codegraph status que le worktree a son propre index local plutôt que d'emprunter l'index de l'arbre principal.
• Préférez codegraph_explore (ou codegraph explore depuis la CLI) aux outils cachés plus étroits (codegraph_node, codegraph_search, codegraph_callers, codegraph_callees, codegraph_impact, codegraph_files, codegraph_status) — tout ce qu'ils retournent arrive déjà en ligne avec codegraph_explore.

Voir INSTALL.md pour les options d'installation, y compris les scripts vérificateurs/installeurs Node.js fournis dans scripts/, nécessaires uniquement pour le chemin d'installation npm ou l'intégration de bibliothèque.