Trail-code : la mémoire d'équipe pour les agents de code

Mardi, votre agent passe vingt minutes à comprendre pourquoi le client HTTP ne réessaie que quatre fois. Il trouve la raison : au-delà, un seul appel peut bloquer plus d'une heure. Jeudi, la session est fermée, et l'agent d'un collègue passe le nombre de tentatives à dix. Personne ne lui avait dit.

Trail-code s'attaque à ce trou de mémoire. C'est un outil en ligne de commande, open source, qui donne aux agents de code deux choses : une carte du code, pour savoir où sont les fonctions et qui les appelle, et des « learnings », des décisions et préférences sauvegardées en fichiers markdown dans le dépôt, pour savoir pourquoi le code est comme il est.

De graft à Trail-code

Le projet s'appelait graft et était publié sous @nanonets/graft. Il a été renommé Trail-code, sous l'organisation trailhq, quand la partie « learnings » est arrivée. Le dépôt a été créé en juillet 2026, il dépasse les 10 000 étoiles mi-octobre, et il est écrit en TypeScript sous licence MIT.

Rien ne casse pour les anciens utilisateurs : la commande graft et l'ancien paquet npm exécutent le même code. La carte du code s'appelle désormais la « graft map », et c'est l'une des deux moitiés de l'outil.

La graft map : où sont les choses

trail init analyse le dépôt avec tree-sitter et construit un graphe de chaque fichier, chaque fonction et chaque appel. Pas de modèle, pas de clé d'API, pas de réseau. Le parsing complet couvre TypeScript, JavaScript, Python, Go, Java, Kotlin, PHP, Swift, R et les composants Vue. Une dizaine d'autres langages, dont Rust, C, C++ et C#, ont une couverture plus sommaire : symboles et appels résolus par nom.

La carte se rafraîchit seule. Avant chaque requête, l'outil vérifie si l'arbre de fichiers a bougé, environ 50 ms sur son propre dépôt, et ne reconstruit que ce qui a changé, modifications non commitées comprises.

Dans Claude Code, l'intégration passe par des hooks. À chaque prompt, un hook ajoute les fichiers et fonctions qui correspondent à la demande. Après chaque modification, un autre affiche ce qui dépend du fichier touché, le « rayon d'impact ». Cursor, Codex, Gemini CLI, Copilot et les autres reçoivent la même carte par des outils MCP et leurs fichiers d'instructions.

C'est la même idée que codebase-memory-mcp et son graphe de code, avec une différence d'approche. codebase-memory-mcp est un serveur que l'agent interroge quand il le décide. Trail-code pousse le contexte dans chaque prompt via les hooks, sans attendre que l'agent pense à demander.

Une option trail build --deep ajoute des résumés en langage naturel de chaque partie du système. Celle-ci appelle un modèle, avec votre propre clé, chez le fournisseur de votre choix.

Les learnings : pourquoi elles sont comme ça

C'est la partie nouvelle, et la plus intéressante. Un learning est un petit fichier markdown, rangé dans .trail/learnings/ et commité avec le code :

---
title: Keep the default retry count at 4
author: Anirudh
date: 2026-10-09
cost: { tokens: 27400 }
touches:
  - client.go
---
 
## Decided
- Keep defaultRetryMax = 4: ten retries with the default backoff can hold one Do() call for over an hour.
 
## Tried and ruled out
- Raising the default to 10 for one customer.
 
## Watch out
- RetryWaitMax caps each wait at 30s, not the total.

Le champ touches relie la décision aux fichiers concernés. La prochaine session qui touche client.go la reçoit avant même d'ouvrir le code. Le champ cost garde ce que la découverte a coûté, d'où les messages du type « saved ~27k tokens » quand un collègue en profite.

Ces fichiers, personne ne les écrit à la main. L'agent les sauvegarde lui-même à des moments précis : après une session qui a demandé du vrai travail d'investigation, ou quand vous le corrigez (« ici on utilise pnpm, pas npm »). Il ne modifie jamais un learning existant. S'il va à l'encontre d'une décision, il l'explique dans le commit et en crée un nouveau.

Il existe deux endroits pour les ranger. Ce qui concerne le code va dans le dépôt, partagé avec l'équipe. Ce qui concerne vos habitudes ou votre machine reste dans ~/.trail/, jamais commité.

Le garde-fou avant la pull request

La commande la plus utile pour une équipe est trail check. Elle compare la branche en cours avec tout ce que l'équipe a décidé :

checking 1 changed file against 1 learning and 0 skills
 
✗ client.go:51
  changes defaultRetryMax from 4 to 10
  Anirudh · Oct 9: Keep defaultRetryMax = 4: ten retries with the
  default backoff can hold one Do() call for over an hour.
 
· 1 conflict · fix it, or say why in the commit message or PR description

L'agent est configuré pour la lancer avant chaque commit, push ou pull request. Le conflit n'est pas bloquant : on corrige, ou on justifie. C'est exactement le comportement qu'on attend d'un collègue qui connaît l'historique.

L'outil signale aussi les chevauchements : si une branche poussée par un collègue modifie la même constante que vous, votre agent le dit juste après votre modification. Tout transite par git. Pas de serveur, pas de compte.

Installer et démarrer

Il faut Node.js. Puis, dans le dépôt :

npm install -g @trailhq/trail-code
trail init

trail init demande quels agents configurer, construit la carte, crée .trail/, et ajoute une barre d'état et des hooks à Claude Code. trail init --dry-run montre ce qu'il écrirait sans rien toucher. Il ne modifie jamais votre CLAUDE.md.

On commite ensuite la configuration pour que l'équipe en profite. La carte elle-même, dans graft/, est un cache local ajouté au .gitignore, comme node_modules :

git add .claude .mcp.json .trail .gitignore .ignore
git commit -m "set up Trail-code"

Les autres commandes du quotidien tiennent en quatre lignes :

Ce que valent les chiffres

Le README est généreux en benchmarks. Sur SWE-bench Verified, un banc d'essai de vrais tickets GitHub validés par les tests des mainteneurs, Claude Sonnet 5 résout 33 tickets sur 50 avec la carte, contre 27 sans, avec 23 % de tokens en moins. Sur leur propre banc de 162 exécutions : 46 % d'appels d'outils en moins, 60 % de temps en moins, correction identique.

Deux réserves. Ces mesures sont publiées par l'éditeur de l'outil, sur un échantillon de 50 tickets pour SWE-bench, ce qui laisse une marge d'erreur réelle sur un écart de six tickets. Et elles ne mesurent que la carte du code, pas les learnings, qui sont la vraie nouveauté. L'honnêteté de la méthode mérite tout de même d'être notée : le README détaille les modèles, les dépôts, les tâches et le mode de notation, et signale que le mode « push » perd trois points de correction sur un corpus.

Ce qu'il lit sur votre machine

Au premier lancement, trail init fait deux lectures qu'il vaut mieux connaître avant d'appuyer sur Entrée.

Il relit vos anciennes sessions Claude Code dans ce dépôt pour retrouver ce que vous avez répété plus d'une fois, et en faire des préférences. La lecture est faite par votre propre Claude Code, sous votre compte : vos messages partent chez Anthropic, et ça compte dans votre quota d'utilisation. Rien ne va chez Trail, selon la documentation.

Si la CLI gh est connectée, il lit aussi les commentaires de revue des 50 dernières pull requests fusionnées, pour en tirer les remarques récurrentes. Les secrets apparents sont filtrés.

Enfin, une télémétrie anonyme est active par défaut. Le fichier TELEMETRY.md liste chaque champ envoyé, et trail telemetry disable ou DO_NOT_TRACK=1 la coupent. Un « espace de travail Trail » partagé est annoncé pour bientôt : c'est là que se dessine le modèle payant, et c'est seulement à ce moment que des learnings quitteraient votre dépôt.

J'ai longtemps tenu des fichiers CLAUDE.md à la main, et ils finissent tous de la même façon : périmés, trop longs, ignorés à moitié. Trail-code propose l'inverse, des décisions courtes, attachées aux fichiers qu'elles concernent, relues en pull request comme du code. La carte est un bon outil parmi d'autres. Les learnings, eux, s'attaquent à un vrai problème d'équipe, et c'est sur eux que je jugerai le projet dans six mois. Pour comprendre comment l'outil s'accroche à l'agent, le guide des hooks Claude Code explique le mécanisme qu'il utilise à chaque prompt.