La recherche de code pour agents a un budget de tokens

Semble a dépassé les 900 étoiles GitHub le 17 mai 2026 avec une thèse sans détour : les agents de programmation gaspillent l’essentiel de leur budget de contexte quand ils lancent grep, ouvrent des fichiers entiers et lisent bien plus de code que la tâche ne l’exige.¹

Cette thèse fonctionne parce qu’elle reformule la recherche de code comme un problème de budget. Un humain peut parcourir vite un résultat rg bruyant et ignorer le superflu. Un agent, lui, paie chaque ligne hors sujet en contexte, en attention et en temps de boucle d’outils.

TL;DR

Semble est une bibliothèque de recherche de code pour agents. Elle propose un serveur MCP, une intégration shell via AGENTS.md ou CLAUDE.md, une CLI et une API Python.¹ Sous le capot, Semble découpe le code, recherche avec BM25 et des embeddings de code Model2Vec statiques, fusionne les listes classées avec Reciprocal Rank Fusion, puis reclasse avec des signaux adaptés au code : pondération des symboles, bonus aux définitions, racines d’identifiants, cohérence de fichier et pénalités de bruit.¹ Son benchmark annonce un NDCG@10 de 0,854 sur environ 1 250 requêtes couvrant 63 dépôts dans 19 langages, proche du score hybride CodeRankEmbed de 0,862, tout en indexant beaucoup plus vite dans le tableau de benchmark.² La leçon produit importante n’est pas « remplacer grep ». Elle est plus précise : un outil de recherche pour agents doit renvoyer le plus petit paquet de preuves permettant au modèle d’agir correctement.

Points clés

• Pour les utilisateurs d’agents de programmation : gardez rg pour les chaînes exactes, mais utilisez une recherche d’extraits classés quand la tâche porte sur un comportement plutôt que sur un token littéral.
• Pour les concepteurs d’outils : optimisez le contexte récupéré, pas seulement la précision de la récupération. L’unité utile, c’est la preuve par token.
• Pour les utilisateurs de Codex et Claude Code : privilégiez un chemin accessible depuis le shell pour les sous-agents, car les outils MCP de premier niveau ne parviennent pas forcément aux agents délégués de la même manière.¹
• Pour les lecteurs de benchmarks : séparez les affirmations de benchmark du fournisseur du comportement local à l’exécution. Mon lancement à froid avec uvx a pris bien plus de temps que le tableau de benchmark de Semble, parce que le démarrage des paquets, du modèle et de l’index dominait.
• Pour l’écriture publique : les outils de récupération ne suppriment pas le travail de citation. Ils rendent seulement le chemin vers les preuves moins coûteux à inspecter.

Pourquoi Grep reste utile, sans suffire

rg reste le bon premier outil pour les chaînes exactes. Si je cherche visible_label_residue, le nom d’une variable d’identifiants ou un nom de fonction, la recherche lexicale doit l’emporter en vitesse et en certitude. Dans mon test local, une requête rg littérale sur des termes de résidu de traduction est revenue en environ un dixième de seconde.⁵

Le problème commence quand l’agent ne connaît pas la chaîne exacte.

Les agents cherchent souvent par intention : « où la barrière i18n du blog vérifie-t-elle les résidus de libellés visibles ? » ou « comment fonctionne la vérification de publication des traductions ? ». La recherche littérale peut encore trouver des lignes utiles, mais l’agent doit choisir des mots, inspecter des dizaines de résultats, lire des fichiers, reformuler la requête et décider quelle ligne contient la réponse. Chaque étape consomme du contexte et crée une occasion de s’arrêter trop tôt.

Semble attaque précisément ce mode d’échec. L’agent peut formuler une requête en langage naturel, puis recevoir des extraits de code classés au lieu de fichiers entiers.¹ Cela ne rend pas rg obsolète. Cela change l’interaction par défaut : on passe de « montrez-moi toutes les lignes qui correspondent à ce terme » à « donnez-moi le plus petit morceau de code utile ».

Cette nuance compte parce que les agents ne lisent pas comme les humains. Un humain peut balayer 80 lignes de sortie de recherche et ne garder en tête que les 3 lignes intéressantes. Les modèles reçoivent toute la sortie sous forme de tokens. Un résultat de recherche bruyant devient une partie de l’environnement de la tâche.

Ce que fait réellement Semble

Le README public de Semble décrit 4 chemins d’intégration : serveur MCP, Bash / AGENTS.md, CLI et API Python.¹ La configuration Codex repose sur une entrée de serveur MCP locale dans ~/.codex/config.toml, et le chemin shell ajoute une section de recherche de code à AGENTS.md ou CLAUDE.md.¹

Le chemin shell compte plus qu’il n’y paraît au premier abord. Le README précise que les sous-agents Claude Code et Codex CLI doivent utiliser l’intégration Bash à la place de MCP, ou en complément, car dans cette configuration les sous-agents ne peuvent pas appeler directement les outils MCP.¹ C’est un point pratique d’interface agent : l’outil de recherche doit exister là où le travail se fait, pas seulement là où la session de premier niveau commence.

La pile de récupération ressemble aussi à la direction que prend la recherche pour agents :

Cette conception correspond à ce que j’ai vu dans les systèmes de récupération locaux : la recherche vectorielle pure rate les identifiants, la recherche par mots-clés pure rate l’intention, et le classement hybride donne à l’agent une meilleure première lecture.⁴

Le benchmark parle de contexte, pas de magie

Le README des benchmarks de Semble présente deux classes de résultats.

La première mesure la qualité et la vitesse de récupération. Le tableau donne Semble à 0,854 NDCG@10, CodeRankEmbed Hybrid à 0,862, BM25 à 0,673 et ripgrep à 0,126. Le benchmark couvre environ 1 250 requêtes sur 63 dépôts dans 19 langages, avec des exécutions CPU uniquement.²

La seconde mesure l’efficacité en tokens. Le benchmark modélise un flux courant d’agent de programmation : découper une requête en mots-clés, exécuter rg --fixed-strings --ignore-case, classer les fichiers par nombre de mots-clés distincts trouvés, puis lire en entier les fichiers correspondants. Face à cette base de comparaison, le benchmark annonce en moyenne 45 692 tokens pour ripgrep plus lectures de fichiers, contre 566 tokens pour Semble, soit une réduction de 98 %.²

Voilà l’affirmation intéressante. Pas « la recherche sémantique bat grep » dans tous les cas. Pas « les agents doivent arrêter d’utiliser la recherche exacte ». L’affirmation est que grep puis lecture envoie trop de code hors sujet dans le modèle quand la tâche n’a besoin que de quelques morceaux.

La méthodologie du benchmark explique aussi où cette affirmation s’applique, et où elle ne s’applique pas. Semble se compare à la lecture intégrale des fichiers correspondants.² Si votre flux de travail utilise déjà rg -n, sed et des plages de lignes chirurgicales, votre base de comparaison est peut-être plus serrée que le modèle grep puis lecture du benchmark. Si votre agent ouvre régulièrement des fichiers entiers après une recherche large, le benchmark ressemble davantage à votre vrai mode d’échec.

Mon test local

J’ai exécuté Semble dans le dépôt du site avec uvx --from semble semble, puis je l’ai comparé à des recherches rg littérales.

J’ai commencé par une requête sur le processus de publication :

semble search "blog translation quality gate release verifier D1" . --top-k 5 --include-text-files

Semble a renvoyé 5 extraits. Le premier résultat résumait la boucle de publication des traductions de blog dans un tableau d’article de migration. Un autre pointait directement vers scripts/i18n-automation/README.md, qui contenait les étapes de barrière de qualité, vérificateur de publication, revue native, commit, push, Railway, Cloudflare et test smoke en production.⁵

La commande rg comparable a répondu vite, mais avec un grand flux de correspondances littérales pour des variables d’identifiants, blog_release_verify et des noms associés dans des scripts, des tests et des documents.⁵ Un humain peut filtrer cela. Un agent doit dépenser du contexte pour faire la même chose.

J’ai ensuite demandé l’implémentation de la barrière :

semble search "where does the blog i18n gate check visible label residue" . --top-k 5 --include-text-files

Le premier résultat de Semble pointait vers le bloc exact de la barrière locale où visible_label_residue est assigné, transformé en erreur et utilisé pour déterminer le statut du constat. La sortie incluait les lignes pertinentes du corps de fonction, plutôt qu’un fichier entier.⁵

La requête rg comparable s’est de nouveau terminée plus vite, mais elle a renvoyé de nombreux résultats dans des tests, des prompts de traduction, des scripts de réparation, le README et l’implémentation de la barrière.⁵

Ce test ne prouve pas le benchmark de Semble. Mon invocation utilisait uvx, téléchargeait des paquets et des ressources de modèle, indexait un gros dépôt mixte, incluait des fichiers Markdown et JSON, et partait d’un chemin à froid. La première requête Semble a pris environ 54 secondes ; la seconde, environ 31 secondes.⁵ Ces chiffres ne correspondent pas au tableau de benchmark du projet, et je ne les citerais pas comme données de performance de Semble.

Le test prouve en revanche la forme du produit. Semble a renvoyé des paquets de preuves plus petits et plus proches d’une réponse. Après deux recherches, semble savings --verbose annonçait environ 38 100 tokens estimés économisés, soit 94 %, selon sa propre méthode d’économie fichier contre extrait.⁵ Il faut traiter cela comme une estimation rapportée par l’outil, pas comme une mesure indépendante, mais la direction correspondait à la sortie visible.

Le bon modèle mental : des paquets de preuves

La recherche pour agents devrait produire des paquets de preuves.

Un paquet de preuves a 4 propriétés :

rg brut donne la localisation et la vitesse. Les lectures de fichiers entiers donnent du contexte, mais trop. La recherche vectorielle donne l’intention, mais peut manquer des noms exacts. Un bon flux de recherche pour agents les combine :

1. Utilisez la recherche exacte quand la tâche nomme un symbole, une erreur, une clé de configuration, un fichier ou une chaîne littérale.
2. Utilisez une recherche sémantique ou hybride avec extraits classés quand la tâche nomme un comportement.
3. N’ouvrez le fichier complet qu’après qu’un extrait a prouvé sa pertinence.
4. Citez le fichier et la plage de lignes dans la réponse finale.
5. Relancez une recherche exacte quand l’extrait suggère un identifiant concret.

Semble encode une grande partie de ce flux dans un outil. L’agent a encore besoin de discernement, et la barrière de preuves a encore besoin d’une trace qu’elle peut inspecter.

Comment Semble change les flux de travail Codex et Claude Code

La question pratique n’est pas de savoir s’il faut installer chaque nouvel outil de recherche. Elle est de savoir quelle place la recherche de code doit occuper dans le contrat d’exécution de l’agent.

Pour les sessions de premier niveau, MCP peut bien fonctionner parce que l’agent voit le schéma de l’outil et appelle directement le serveur. Le README de Semble inclut des exemples de configuration MCP pour Claude Code, Codex, OpenCode, Cursor et d’autres clients compatibles MCP.¹

Pour le travail délégué, l’accès shell peut compter davantage. Le README de Semble mentionne explicitement l’intégration Bash pour les sous-agents Claude Code et Codex CLI.¹ Un sous-agent qui ne peut pas atteindre l’outil MCP de premier niveau peut tout de même lancer une commande shell si le flux de travail lui apprend quand et comment le faire.

La meilleure intégration peut donc sembler très ordinaire :

## Code Search

Use `semble search` when looking for behavior or related implementation.
Use `rg` when looking for an exact string, symbol, file name, or config key.
Open full files only after the search result proves relevance.
Report file path and line range when citing evidence.

Ce type d’instruction vaut mieux qu’une règle vague du genre « utilisez la recherche sémantique », parce qu’il nomme la décision d’orientation. L’agent apprend quel outil convient à quelle question.

Ce que je ne ferais pas

Je ne remplacerais pas rg.

Le test local l’a rendu clair. rg a répondu aux requêtes littérales en environ un dixième de seconde. Semble a renvoyé de meilleurs paquets pour des requêtes formulées en termes de comportement, mais mon invocation shell à froid avait un vrai coût de démarrage et d’indexation.⁵

Je ne traiterais pas l’affirmation des 98 % de tokens économisés comme universelle. Le benchmark compare Semble à grep plus lectures de fichiers entiers. L’affirmation est juste lorsque cette base de comparaison ressemble au comportement de l’agent. Elle surestime le gain lorsqu’un flux discipliné lit déjà des plages de lignes étroites.

Je ne cacherais pas le choix d’orientation dans une boîte noire. Les agents doivent savoir s’ils font une recherche exacte, une découverte sémantique, une exploration de code associé ou une confirmation par preuves. L’usage d’outils sans règles d’orientation devient une autre source d’échec plausible, le même problème d’interface que derrière le travail agentique piloté par chat.

Pourquoi Semble a sa place à côté de l’article sur Grep

Le récent article « Is Grep All You Need? » a testé grep et la récupération vectorielle sur Chronos, Claude Code, Codex CLI et Gemini CLI pour de la question-réponse conversationnelle à mémoire longue. Dans ce contexte, grep intégré a battu la récupération vectorielle intégrée, mais la leçon plus profonde de l’article compte davantage : l’environnement d’exécution a changé le résultat autant que la méthode de récupération.³

Semble pointe vers la même couche opérationnelle, côté code. La qualité de recherche ne vit pas seulement dans le récupérateur. Elle vit dans :

• la manière dont la requête est formée ;
• l’existence conjointe de chemins exacts et sémantiques ;
• la quantité de contexte renvoyée par l’outil ;
• la présence, dans les extraits, de preuves par fichier et par ligne ;
• l’ouverture de fichiers entiers par l’agent uniquement quand c’est nécessaire ;
• l’accès des agents délégués à l’outil ;
• la citation, dans la réponse finale, de ce que la recherche a réellement trouvé.

L’enveloppe reste le produit. La recherche ne devient utile que lorsque l’environnement d’exécution transforme la récupération en preuves, ce qui explique pourquoi la surface de contrôle du design agentique compte autant que l’algorithme de récupération.

Le standard que je veux

Un outil de recherche pour agents devrait rapporter plus que des correspondances.

Il devrait indiquer :

• la requête exécutée ;
• le chemin de récupération utilisé ;
• le fichier et la plage de lignes ;
• l’extrait ;
• une estimation des tokens renvoyés ;
• si le résultat vient d’une récupération exacte, sémantique ou hybride ;
• quand l’agent est passé d’un extrait à une lecture de fichier complet.

Cette sortie rendrait la recherche de code auditable. Un réviseur pourrait voir si l’agent a trouvé le bon code, lu assez de contexte et évité de se noyer dans des fichiers hors sujet. Le même principe guide les traces d’exécution d’agents : la preuve vit dans le chemin, pas seulement dans la réponse.

Semble avance déjà dans cette direction en traitant la taille des extraits et les économies de tokens comme des préoccupations produit de premier ordre. La prochaine étape pour les environnements d’exécution d’agents consiste à rendre ce chemin de preuves visible dans les paquets de revue et les réponses finales.

Le but n’est pas d’avoir une recherche plus élégante. Le but est d’avoir moins d’affirmations non étayées par token.

FAQ

Semble remplace-t-il grep ?

Non. Utilisez rg pour les chaînes exactes, les symboles, les clés de configuration, les noms de fichiers et les confirmations rapides. Utilisez une récupération par extraits à la Semble quand la tâche décrit un comportement ou une implémentation associée, et que l’agent ne connaît pas l’identifiant exact.

Votre test local confirme-t-il les affirmations de vitesse de Semble ?

Non. Mon invocation locale uvx a pris environ 54 secondes pour la première requête et 31 secondes pour la seconde, surtout parce que le démarrage des paquets et du modèle, puis l’indexation, dominaient cette exécution ad hoc. Le tableau de benchmark de Semble rapporte des mesures contrôlées beaucoup plus rapides, mais mon exécution locale doit être traitée comme une preuve de flux de travail, pas comme un benchmark de performance.²⁵

Votre test local confirme-t-il la direction des économies de tokens ?

Oui, au niveau du flux de travail. Semble a renvoyé des extraits beaucoup plus petits que la sortie rg littérale large, et sa commande savings a annoncé environ 38 100 tokens estimés économisés après deux recherches. Ce chiffre vient de la propre méthode de comptabilité de Semble : traitez-le donc comme de la télémétrie d’outil plutôt que comme une preuve indépendante.⁵

Pourquoi la recherche de code pour agents compte-t-elle pour Codex et Claude Code ?

Les agents perdent en qualité quand la recherche déverse trop de contexte ou masque trop de preuves. Un bon flux de travail apprend à l’agent quand utiliser la recherche exacte, quand utiliser la récupération par extraits classés, quand ouvrir des fichiers complets et comment citer le résultat.

Les équipes doivent-elles ajouter Semble à AGENTS.md ?

Seulement après l’avoir testé sur leur base de code. Commencez par une instruction : utiliser la recherche par extraits classés pour les questions formulées en termes de comportement, et rg pour les chaînes exactes. Mesurez si les agents trouvent les bons fichiers plus vite et lisent moins de lignes hors sujet.

Références