Code Map

Un agent qui débarque — ou vous, à 2h du matin dans un dépôt inconnu — perd ses dix premières minutes à chercher où vit réellement getLocalizedPath et ce qui en dépend. Code Map supprime cette taxe. brainclaw parse votre code avec Tree-sitter — JavaScript, TypeScript/TSX, Python, PHP et Java dans un seul index — et enregistre les symboles que chaque fichier définit (fonctions, classes, types, interfaces, composants et hooks React), ce qu’il importe et exporte, et comment les fichiers s’articulent — puis répond à « que dois-je lire avant d’éditer ça ? » en un seul appel.

C’est une aide à la découverte, pas un artefact de build : il ne modifie jamais votre code, ne bloque jamais bclaw_work, et l’index (shards JSONL sous .brainclaw/code/) peut être supprimé sans risque — un refresh le reconstruit.

brainclaw code-map status                     # couverture + fraîcheur, ne parse jamais
brainclaw code-map refresh                    # incrémental : uniquement les fichiers modifiés
brainclaw code-map find getLocalizedPath
#   [10.0] getLocalizedPath  function — src/i18n/config.ts
brainclaw code-map brief src/i18n/config.ts
#   → fichiers à lire ensuite, classés (max 12) + les décisions et pièges attachés

Jamais faux en silence

Code Map est pull-based — pas de démon, pas de réindexation en arrière-plan. Chaque status / find / brief recalcule un badge de fraîcheur à partir du statut git et des hash de fichiers, si bien qu’un index périmé est toujours visible au lieu d’induire silencieusement en erreur :

Badge	Signification
fresh	Correspond à l’arbre de travail, à la config d’extraction et aux binaires du parseur
stale_changed_files	Des fichiers indexés ont changé sur disque depuis leur parsing
stale_extractor / stale_grammar	La config ou une grammaire Tree-sitter a été bumpée
missing_index	Aucun index n’existe encore pour ce projet

refresh --changed (le défaut) ne reparse que les fichiers dont le contenu a changé et répare stale_extractor / stale_grammar sur ce même chemin économique ; --all fait une reconstruction complète avec compaction des orphelins. Un verrou projet déjà tenu fait échouer le refresh immédiatement — il ne bloque jamais votre travail, donc le pire cas est un rappel d’une ligne « lancez refresh », jamais une réponse fausse. Le parseur Tree-sitter est livré en WASM embarqué et n’est chargé qu’au premier parsing, donc status / find / brief restent instantanés même avant que le moteur soit sollicité.

Sur le serveur MCP, et par projet

Les quatre mêmes appels sont des outils MCP — bclaw_code_status, bclaw_code_find, bclaw_code_brief, bclaw_code_refresh — donc un agent capable les atteint en cours de tâche sans shell, chacun portant le même badge de fraîcheur ; les outils de lecture ne déclenchent jamais de parsing. Dans un monorepo l’index est par projet : lancez-le dans apps/api et vous obtenez la carte propre à cet enfant. La résolution de projet de brainclaw route Code Map vers le projet dans lequel vous travaillez — le même scoping qui alimente bclaw_work et bclaw_switch — sans jongler avec --cwd.

Et comme brainclaw détient déjà vos décisions et vos pièges, brief ne se contente pas de pointer vers du code — il fait remonter la mémoire attachée à ce périmètre. Interrogez un module et vous obtenez les fichiers à lire ensuite et le piège que quelqu’un y a laissé le mois dernier.