GitNexus : l’agent IA qui lit l’intégralité d’un codebase avant d’y toucher

Le problème que GitNexus résout

Depuis que j’utilise Claude Code de façon intensive sur des projets avec des codebases de taille réelle (20 000 lignes et plus), j’observe le même pattern : l’agent explore le code à tâtons. Il lance un grep pour trouver une fonction, lit le fichier qui la contient, découvre une dépendance, lance un autre grep, lit un autre fichier, et ainsi de suite. Sur une session typique de modification d’une fonctionnalité transversale, j’ai compté jusqu’à 30 à 40 opérations de lecture avant que l’agent ne touche une ligne de code.

Ce n’est pas un défaut d’implémentation de Claude Code. C’est une limite structurelle : l’agent ne dispose d’aucune représentation pré-calculée du graphe de dépendances. Il reconstitue cette connaissance à chaque session, par exploration séquentielle, au coût d’un volume de tokens considérable.

GitNexus attaque exactement ce problème. Plutôt que de laisser l’agent explorer à la volée, il indexe le dépôt une fois, construit un graphe de connaissances complet (fonctions, imports, call chains, clusters fonctionnels) et expose ce graphe via 16 outils MCP. L’agent pose une question structurée, reçoit une réponse précise, et n’a plus besoin de lire de fichiers.

Le résultat documenté dans les conditions du cas Satapathy (un système à 17 agents en production, étude d’avril 2026, publiée par Pebblous) : 58 appels d’outils réduits à 7 sur 3 requêtes, soit -88 %. Tokens de récupération : de ~13 750 à ~3 500, soit -74 %. Je détaille les conditions et les limites de ce chiffre dans la section benchmark, il ne s’agit pas d’un résultat universel.

Comment ça marche : graphe, Tree-sitter, traitement local

L’indexation AST par Tree-sitter

GitNexus parse le code source via Tree-sitter, un parseur AST (Abstract Syntax Tree) multi-langage. Pour chaque fichier, il extrait les symboles (fonctions, classes, variables exportées), les dépendances (imports, appels de fonctions, héritages de classes) et les relations entre eux. Il supporte 14 langages : TypeScript, JavaScript, Python, Java, Kotlin, C#, Go, Rust, PHP, Ruby, Swift, C, C++, Dart.

À noter : le support n’est pas homogène sur tous ces langages. Vue.js est absent. Kotlin, Swift, Go et Rust ont une couverture incomplète (issues GitHub ouvertes #2035, #2289 au moment où j’écris ces lignes). Si votre stack principale est TypeScript ou Python, vous êtes sur la partie la mieux supportée.

Le graphe de connaissances

L’AST seul ne suffit pas. GitNexus construit par-dessus un graphe de dépendances, stocké dans LadybugDB (une base embarquée maison). Ce graphe modélise les relations transitives : si A appelle B qui appelle C, le graphe connaît le chemin complet, là où grep ne verrait que les occurrences textuelles directes.

Dans les conditions testées par Satapathy, le graphe a détecté 2,7 fois plus de dépendances que grep sur le même codebase. Ces dépendances transitives sont précisément celles qui provoquent les régressions de refactoring non anticipées.

La recherche est hybride : BM25 (indexation texte classique) combiné à des embeddings vectoriels (activables via le flag --embeddings) avec un ranking RRF (Reciprocal Rank Fusion). La détection de clusters fonctionnels (domaines du code qui travaillent ensemble) utilise l’algorithme Leiden.

Traitement 100 % local

Point que je veux mettre en avant explicitement : tout le traitement se fait en local. L’index est stocké dans un dossier .gitnexus/ à la racine du projet, qui est gitignored par défaut. Aucune ligne de code n’est envoyée vers un serveur externe lors de l’indexation.

Pour une PME en Suisse romande qui travaille sur du code propriétaire, c’est un argument de poids. On ne parle pas d’un service cloud qui indexe votre codebase sur ses serveurs : on parle d’un outil CLI qui tourne sur votre machine ou votre VPS, et qui expose ses résultats à l’agent IA via le protocole MCP en local.

Prérequis avant de commencer

Pour les grammaires Tree-sitter avancées (Dart, Proto, Swift, Kotlin) :

• Python3
• make et g++ (compilation de modules natifs)

Si vous voulez éviter la compilation C++ (recommandé pour un premier essai) :

export GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1

Cette variable d’environnement désactive les grammaires qui nécessitent une compilation C++ et réduit le temps d’installation de façon significative.

Installation et configuration pas à pas

Étape 1 : installation globale

npm install -g gitnexus

Vérifier que l’installation s’est bien passée :

gitnexus --version
# gitnexus v1.6.8

Si vous ne voulez pas d’installation globale ou si vous voulez tester rapidement sans polluer votre environnement Node, la version ponctuelle suffit :

npx gitnexus analyze

Étape 2 : détection automatique des éditeurs

gitnexus setup

Cette commande détecte les éditeurs présents sur le système (Claude Code, Cursor, VS Code avec extension MCP) et écrit la configuration MCP appropriée dans les fichiers de config correspondants. C’est la méthode recommandée pour une intégration stable, car elle écrit un chemin absolu vers le binaire plutôt que de passer par npx à chaque démarrage.

Étape 3 : indexer le dépôt

Naviguer à la racine du projet à indexer, puis :

# Indexation standard (AST + graphe + FTS)
gitnexus analyze

# Rebuild complet (utile après des changements structurels importants)
gitnexus analyze --force

# Activer la recherche sémantique par embeddings vectoriels
gitnexus analyze --embeddings

# Générer les fichiers SKILL.md par cluster fonctionnel
gitnexus analyze --skills

L’indexation crée le dossier .gitnexus/ à la racine du projet. Sur un projet de taille moyenne (5 000 à 10 000 fichiers), compter quelques minutes la première fois. Les runs suivants sont incrémentaux.

Le flag --skills génère un fichier SKILL.md par cluster fonctionnel détecté par l’algorithme Leiden. Ces fichiers décrivent en langage naturel ce que fait chaque module du code, et sont injectés automatiquement dans le contexte de l’agent.

Étape 4 : intégration Claude Code (recommandée)

Si gitnexus setup n’a pas détecté Claude Code automatiquement, la commande manuelle :

claude mcp add gitnexus -- npx -y gitnexus@latest mcp

Cette commande enregistre GitNexus comme serveur MCP dans la configuration Claude Code. L’alternative via gitnexus setup est plus stable car elle évite le démarrage npx à chaque session.

Pour vérifier que le serveur MCP est bien enregistré dans Claude Code :

claude mcp list
# gitnexus    npx -y gitnexus@latest mcp    (ou chemin absolu si via gitnexus setup)

Étape 5 : intégration Cursor

Éditer (ou créer) ~/.cursor/mcp.json :

{
  "mcpServers": {
    "gitnexus": {
      "command": "npx",
      "args": ["-y", "gitnexus@latest", "mcp"]
    }
  }
}

Étape 6 : démarrer le serveur MCP manuellement (optionnel)

# Mode stdio (pour les clients MCP qui lisent sur stdin/stdout)
gitnexus mcp

# Mode HTTP local (pour l'interface web de visualisation du graphe)
gitnexus serve

Étape 7 : configuration de projet via .gitnexusrc

Créer un fichier .gitnexusrc à la racine du projet pour personnaliser le comportement :

{
  "defaultBranch": "develop",
  "skipSkills": true,
  "embeddings": true,
  "workerTimeout": 60
}

Les options disponibles dans ce fichier surpassent les flags CLI et sont versionnables avec le projet.

Étape 8 : déploiement Docker pour une équipe

Pour déployer GitNexus sur un VPS partagé d’équipe, les images Docker sont disponibles (signées Cosign, publiées sur GHCR et Docker Hub) :

docker compose up -d

C’est la méthode recommandée pour un déploiement multi-développeurs où chacun se connecte au même serveur MCP d’équipe plutôt que d’indexer localement.

Ce que Claude Code reçoit concrètement

Une fois configuré, Claude Code dispose de 16 outils MCP exposés par GitNexus. Les principaux :

• query : recherche dans le graphe (remplace grep dans la plupart des cas)
• impact : analyse l’impact d’une modification sur le reste du codebase avant de toucher quoi que ce soit
• context : récupère le contexte structurel complet d’un symbole (qui l’appelle, qui il appelle)
• detect_changes : détecte un index stale après un commit et invite à réindexer
• rename : renommage multi-fichiers assisté par le graphe
• cypher : requêtes directes sur le graphe en syntaxe Cypher (pour les cas avancés)
• generate_map : carte visuelle des dépendances

Au-delà des outils, Claude Code reçoit aussi 4 skills bundlés (Exploration, Debugging, Impact Analysis, Refactoring) et des hooks qui opèrent automatiquement :

Hooks PreToolUse : chaque fois que Claude Code s’apprête à lancer un grep ou un glob classique, le hook enrichit automatiquement la requête avec le contexte graphe. L’agent n’a pas besoin de savoir qu’il y a un graphe derrière : ses outils habituels deviennent plus précis sans changer sa façon de travailler.

Hooks PostToolUse : après chaque commit, le hook détecte si l’index graphe est devenu stale (le code a changé mais le graphe n’a pas encore été mis à jour) et propose automatiquement une réindexation incrémentale.

Les instructions injectées dans le CLAUDE.md du projet prescrivent à l’agent :

- Exécuter impact({target: "symbolName"}) AVANT toute modification
- Lancer detect_changes() avant tout commit
- Utiliser query() plutôt que grep pour l'exploration
- Ne jamais ignorer les retours HIGH/CRITICAL de l'analyse d'impact

Ces instructions s’appliquent automatiquement dès que le projet contient le CLAUDE.md généré par GitNexus. Ce n’est pas une suggestion : c’est une règle injectée dans le contexte de l’agent à chaque session.

Avant et après : le benchmark terrain

Je présente ces chiffres avec toutes leurs conditions, parce que les citer sans contexte serait trompeur.

Source : blog Pebblous, rapport de production daté d’avril 2026, rapportant l’étude de Sidharth Satapathy. Ce n’est pas un paper peer-reviewed. C’est un cas unique, non répliqué indépendamment à ce jour. À traiter comme une mesure terrain documentée, pas comme une vérité universelle.

Conditions : environnement de production à 17 agents, budgets tokens étagés (Tier 1 environ 900 tokens, Tier 2 environ 400, Tier 3 environ 50).

Ce que ce tableau ne dit pas : la taille du codebase, le langage principal, la structure du projet, ni si les conditions ont été reproduites sur d’autres projets. Sur un projet de 500 fichiers bien structurés, les gains seront différents de ceux observés sur un monorepo de 20 000 fichiers avec des dépendances transversales complexes.

Le résultat le plus intéressant n’est pas dans le tableau principal. Dans les conditions testées, le graphe a détecté 2,7 fois plus de dépendances que grep sur le même codebase. Ce sont les dépendances transitives : A appelle B qui appelle C, et grep sans GitNexus ne voit A-B et B-C que si on lui demande explicitement les deux requêtes. GitNexus les modélise en une seule relation A-C traversable en une requête.

C’est cette capacité à voir les dépendances non évidentes qui rend l’outil pertinent pour le refactoring de code legacy, où les effets de bord non anticipés sont précisément le risque principal.

Limites et pièges à nommer sans détour

Piège 1 : OOM sur les très grands dépôts

Node.js consomme beaucoup de mémoire lors de l’indexation initiale. Sur un dépôt de plus de 10 000 fichiers, le processus risque un OOM (Out of Memory) sur Linux, documenté dans l’issue #1983. La limite de la Web UI est encore plus basse : environ 5 000 fichiers sans activer le mode backend.

Si vous travaillez sur le noyau Linux ou un monorepo d’entreprise de cette taille, tester d’abord sur un sous-répertoire et surveiller la consommation mémoire.

Piège 2 : 508 releases en 5 mois = breaking changes fréquents

GitNexus est un projet de 5 mois (créé début 2026). Il avait 508 releases au 24 juin 2026, avec plusieurs release candidates par jour en ce moment. La cadence est agressive, et les breaking changes sont fréquents entre versions.

Si vous l’intégrez dans un workflow d’équipe, épingler une version précise :

npm install -g gitnexus@1.6.8

Plutôt que @latest qui peut introduire une régression du jour au lendemain. Suivre le changelog avant chaque mise à jour.

Piège 3 : Windows WSL

L’outil detect_changes crash avec @ladybugdb/core 0.17.1 sur Windows WSL (issue #2233 ouverte). Si votre équipe développe sous Windows, vérifier l’état de cette issue avant d’adopter GitNexus en équipe.

Piège 4 : support langages incomplet

14 langages déclarés, mais des niveaux de support variables. Vue.js est absent. Kotlin, Swift, Go et Rust ont des gaps de couverture documentés. Si votre stack inclut beaucoup de Vue, vous n’obtiendrez pas l’analyse de composants que vous attendez.

Piège 5 : bus factor élevé

Malgré plus de 23 contributeurs sur le cycle v1.6.5, les décisions architecturales du projet restent centralisées sur un mainteneur principal. C’est un risque à prendre en compte pour un outil critique dans un workflow de production : si le mainteneur perd de l’intérêt ou si la direction du projet change, il n’y a pas encore d’organisation suffisamment robuste pour assurer la continuité.

Piège 6 : la fausse impersonation crypto

Un signal d’alerte documenté par Pebblous et dans le README officiel : une campagne d’impersonation au nom de GitNexus via Pump.fun (plateforme de tokens crypto) a potentiellement gonflé la visibilité du projet. Les 42 000 étoiles GitHub ne sont pas nécessairement toutes organiques. Je le mentionne pour nuancer les chiffres de popularité, pas pour disqualifier l’outil sur le fond, qui reste techniquement solide.

So-what PME suisse romande : quand l’adopter, quand s’abstenir

La licence PolyForm Noncommercial : lisez-la avant de déployer

Qu’est-ce que ça signifie concrètement ? Si vous développez un produit commercial (un SaaS, une application vendue, un service facturé) et que vous intégrez GitNexus dans votre workflow de développement, vous êtes potentiellement en violation de licence. La zone grise est large, et Akon Labs n’a pas publié de tarif pour une licence commerciale.

Un cas documenté : LangWatch a migré son outillage vers CodeGraphContext (licence MIT) précisément pour éviter le risque PolyForm NC. Ce n’est pas une décision théorique, c’est ce que fait une équipe technique sérieuse face à une licence restrictive dans un contexte commercial.

Ma recommandation : si vous êtes une PME qui développe un produit commercial, contactez Akon Labs avant tout déploiement étendu, ou utilisez une alternative MIT comme CodeGraphContext. Pour un usage interne de R&D, pour un projet open source, ou pour un développeur indépendant qui travaille sur ses propres outils non commerciaux, la version OSS est parfaitement utilisable.

L’argument confidentialité locale

Pour les PME suisses qui travaillent sur du code sensible (fintech, medtech, solutions B2B propriétaires), le traitement 100 % local de GitNexus est un avantage réel. L’index reste sur votre machine ou votre VPS, dans un dossier gitignored. Vous n’uploadez pas votre codebase vers un service tiers. C’est une différence structurelle avec des solutions SaaS d’analyse de code.

Quand l’adopter

• Vous avez un monorepo ou un codebase legacy de taille significative (10 000 lignes et plus)
• Vous utilisez Claude Code de façon intensive et vous voyez l’agent faire des dizaines de greps à chaque session
• Votre stack principale est TypeScript, JavaScript ou Python (couverture la plus solide)
• Vous avez la capacité de suivre les breaking changes (l’outil évolue vite)
• Vous n’êtes pas dans un contexte commercial strict (ou vous avez négocié une licence avec Akon Labs)

Quand s’abstenir

• Votre projet est commercial et vous n’avez pas clarifié la licence avec Akon Labs
• Votre stack est principalement Vue.js, Swift ou Kotlin (couverture incomplète)
• Vous êtes sur Windows WSL et le bug detect_changes n’est pas encore résolu
• Votre dépôt dépasse 10 000 fichiers et vous n’avez pas testé la limite OOM
• Vous voulez un outil stable pour une équipe de production critique (508 releases en 5 mois = outil en construction rapide, pas encore stabilisé)

Ce que ça change concrètement

Pour une équipe de 3 développeurs qui utilise Claude Code sur un monorepo de 50 000 lignes de TypeScript, GitNexus peut transformer chaque session de refactoring : là où l’agent passait 15 à 20 minutes à explorer le code avant de proposer une modification, il pose 2 ou 3 questions MCP au graphe et dispose immédiatement d’une carte complète des dépendances. Le coût en tokens est réduit, les modifications proposées sont mieux informées des effets de bord. C’est un gain qui s’accumule sur la durée, à condition de gérer la cadence de mises à jour et d’avoir clarifié le cadre de licence.