La búsqueda de código para agentes tiene un presupuesto de tokens

Semble superó las 900 estrellas en GitHub el 17 de mayo de 2026 con una afirmación directa: los agentes de programación desperdician la mayor parte de su presupuesto de contexto cuando usan grep, abren archivos completos y leen mucho más código del que necesita la tarea.¹

La afirmación funciona porque replantea la búsqueda de código como un problema de presupuesto. Una persona puede revisar por encima un resultado ruidoso de rg e ignorar lo que sobra. Un agente paga por cada línea irrelevante en contexto, atención y tiempo de bucles de herramientas.

Resumen rápido

Semble es una biblioteca de búsqueda de código para agentes. Ofrece un servidor MCP, integración de línea de comandos mediante AGENTS.md o CLAUDE.md, una CLI y una API de Python.¹ Por debajo, Semble divide el código en fragmentos, busca con BM25 más embeddings de código estáticos de Model2Vec, fusiona las listas clasificadas con Reciprocal Rank Fusion y luego reordena los resultados con señales orientadas al código, como ponderación de símbolos, refuerzo de definiciones, raíces de identificadores, coherencia de archivo y penalizaciones por ruido.¹ Su prueba comparativa informa un NDCG@10 de 0,854 en unas 1.250 consultas sobre 63 repositorios en 19 lenguajes, cerca de la puntuación híbrida de CodeRankEmbed de 0,862, pero con una indexación mucho más rápida en la tabla de la prueba comparativa.² La lección importante del producto no es “reemplazar grep”. Es más precisa: una herramienta de búsqueda para agentes debe devolver el paquete de evidencia más pequeño que permita al modelo actuar correctamente.

Ideas clave

• Para usuarios de agentes de programación: conserva rg para cadenas exactas, pero usa búsqueda con fragmentos clasificados cuando la tarea describe un comportamiento y no un token literal.
• Para quienes crean herramientas: optimiza el contexto recuperado, no solo la precisión de la recuperación. La unidad útil es evidencia por token.
• Para usuarios de Codex y Claude Code: prefiere una ruta accesible desde la línea de comandos para subagentes, porque las herramientas MCP de nivel superior quizá no lleguen a los agentes delegados de la misma manera.¹
• Para quienes leen pruebas comparativas: separa las afirmaciones comparativas del proveedor del comportamiento local en ejecución. Mi ejecución fría con uvx tardó mucho más que la tabla de pruebas comparativas de Semble porque dominaron el arranque de paquetes/modelos y la indexación.
• Para escritura pública: las herramientas de recuperación no eliminan el trabajo de citación. Solo abaratan la inspección del camino de evidencia.

Por qué Grep sigue siendo bueno, y aun así no alcanza

rg sigue siendo la primera herramienta correcta para cadenas exactas. Si necesito visible_label_residue, el nombre de una variable de credenciales o el nombre de una función, la búsqueda léxica debería ganar en velocidad y certeza. En mi prueba local, una consulta literal de rg para términos de residuo de traducción respondió en alrededor de una décima de segundo.⁵

El problema empieza cuando el agente no conoce la cadena exacta.

Los agentes suelen buscar por intención: “dónde revisa la puerta de calidad de i18n del blog el residuo en etiquetas visibles” o “cómo funciona la verificación de lanzamiento de traducciones”. La búsqueda literal todavía puede encontrar líneas útiles, pero el agente tiene que elegir palabras, inspeccionar docenas de resultados, leer archivos, reformular la consulta y decidir qué línea contiene la respuesta. Cada paso consume contexto y crea una oportunidad de detenerse demasiado pronto.

Semble ataca ese modo de falla específico. Permite que el agente consulte en lenguaje natural y devuelve fragmentos de código clasificados en lugar de archivos completos.¹ Eso no vuelve obsoleto a rg. Cambia la interacción predeterminada de “muéstrame todas las líneas que coinciden con este término” a “dame el recorte útil más pequeño de código”.

Esa diferencia importa porque los agentes no leen como las personas. Una persona puede mirar 80 líneas de salida de búsqueda y quedarse mentalmente solo con las 3 interesantes. Los modelos reciben toda la salida como tokens. Un resultado de búsqueda ruidoso pasa a formar parte del entorno de la tarea.

Qué hace Semble en realidad

El README público de Semble describe 4 rutas de integración: servidor MCP, Bash / AGENTS.md, CLI y API de Python.¹ La configuración para Codex es una entrada local de servidor MCP en ~/.codex/config.toml, y la ruta de línea de comandos agrega una sección de búsqueda de código a AGENTS.md o CLAUDE.md.¹

La ruta de línea de comandos importa más de lo que parece al principio. El README indica que los subagentes de Claude Code y Codex CLI deberían usar la integración con Bash en lugar de MCP, o junto con ella, porque en esa configuración los subagentes no pueden llamar directamente a las herramientas MCP.¹ Es un punto práctico de interfaz para agentes: la herramienta de búsqueda tiene que existir donde ocurre el trabajo, no solo donde empieza la sesión de nivel superior.

La pila de recuperación también se parece a la dirección que está tomando la búsqueda para agentes:

Ese diseño coincide con lo que he visto en sistemas locales de recuperación: la búsqueda puramente vectorial pierde identificadores, la búsqueda puramente por palabras clave pierde intención, y la clasificación híbrida le da al agente una mejor primera lectura.⁴

La afirmación de la prueba comparativa trata de contexto, no de magia

El README de pruebas comparativas de Semble informa 2 clases distintas de resultados.

La primera mide calidad y velocidad de recuperación. La tabla sitúa a Semble en 0,854 NDCG@10, CodeRankEmbed Hybrid en 0,862, BM25 en 0,673 y ripgrep en 0,126. La prueba comparativa cubre unas 1.250 consultas sobre 63 repositorios en 19 lenguajes, con ejecuciones solo en CPU.²

La segunda mide eficiencia de tokens. La prueba comparativa modela un flujo común de agentes de programación: dividir una consulta en palabras clave, ejecutar rg --fixed-strings --ignore-case, clasificar archivos por coincidencias de palabras clave distintas y luego leer completos los archivos coincidentes. Frente a esa línea base, la prueba comparativa informa un promedio de 45.692 tokens para ripgrep más lecturas completas de archivos, contra 566 tokens para Semble, una reducción del 98%.²

Esa es la afirmación interesante. No “la búsqueda semántica vence a grep” en cualquier contexto. No “los agentes deberían dejar de usar búsqueda exacta”. La afirmación es que grep más lectura envía demasiado código irrelevante al modelo cuando la tarea solo necesita unos pocos fragmentos.

La metodología de la prueba comparativa también explica dónde debería y no debería aplicarse la afirmación. Semble se compara contra la lectura completa de los archivos coincidentes.² Si tu flujo ya usa rg -n, sed y rangos de líneas quirúrgicos, tu línea base quizá sea más ajustada que el modelo grep más lectura de la prueba comparativa. Si tu agente abre archivos enteros de forma rutinaria después de una búsqueda amplia, la prueba comparativa se parece más a tu modo de falla real.

Mi prueba local

Ejecuté Semble en el repositorio del sitio mediante uvx --from semble semble y luego lo comparé con búsquedas literales de rg.

Empecé con una consulta sobre el proceso de lanzamiento:

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

Semble devolvió 5 fragmentos. El resultado principal resumía el ciclo de lanzamiento de traducciones del blog en una tabla de un artículo de migración. Otro resultado apuntaba directamente a scripts/i18n-automation/README.md, que contenía los pasos de puerta de calidad, verificador de lanzamiento, revisión nativa, commit, push, Railway, Cloudflare y prueba de humo en vivo.⁵

El comando rg comparable respondió rápido, pero devolvió un gran flujo de coincidencias literales para variables de credenciales, blog_release_verify y nombres relacionados en scripts, pruebas y documentación.⁵ Una persona puede filtrar eso. Un agente tiene que gastar contexto para hacer lo mismo.

Después pregunté por la implementación de la puerta:

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

El resultado principal de Semble apuntó al bloque exacto de la puerta local donde visible_label_residue se asigna, se convierte en error y afecta el estado del hallazgo. La salida incluía las líneas relevantes del cuerpo de la función, no un archivo completo.⁵

La consulta comparable de rg volvió a terminar más rápido, pero devolvió muchas coincidencias en pruebas, prompts de traducción, scripts de reparación, el README y la implementación de la puerta.⁵

Esa prueba no demuestra la prueba comparativa de Semble. Mi invocación usó uvx, descargó paquetes y recursos de modelo, indexó un repositorio mixto grande, incluyó archivos Markdown y JSON, y se ejecutó desde una ruta fría. La primera consulta de Semble tardó unos 54 segundos; la segunda, unos 31 segundos.⁵ Esos números no coinciden con la tabla de pruebas comparativas del proyecto, y no los citaría como datos de rendimiento de Semble.

La prueba sí demuestra la forma del producto. Semble devolvió paquetes de evidencia más pequeños y más cercanos a una respuesta. Después de 2 búsquedas, semble savings --verbose informó unos 38.100 tokens estimados ahorrados, un 94%, usando su propio método de ahorro archivo-versus-fragmento.⁵ Trata eso como una estimación reportada por la herramienta, no como una medición independiente, pero la dirección coincidía con la salida visible.

El modelo mental correcto: paquetes de evidencia

La búsqueda para agentes debería producir paquetes de evidencia.

Un paquete de evidencia tiene 4 propiedades:

rg sin procesar da ubicación y velocidad. Las lecturas de archivos completos dan contexto, pero demasiado. La búsqueda vectorial da intención, pero puede perder nombres exactos. Un buen flujo de búsqueda para agentes las combina:

1. Usa búsqueda exacta cuando la tarea nombre un símbolo, error, clave de configuración, archivo o cadena literal.
2. Usa búsqueda semántica o híbrida con fragmentos clasificados cuando la tarea nombre un comportamiento.
3. Abre el archivo completo solo después de que un fragmento demuestre relevancia.
4. Cita el archivo y el rango de líneas en la respuesta final.
5. Vuelve a intentar con búsqueda exacta cuando el fragmento sugiera un identificador concreto.

Semble codifica buena parte de ese flujo como herramienta. El agente todavía necesita criterio, y la puerta de evidencia todavía necesita una traza que pueda inspeccionar.

Cómo cambia Semble los flujos de trabajo de Codex y Claude Code

La pregunta práctica no es si conviene instalar toda herramienta nueva de búsqueda. La pregunta es dónde pertenece la búsqueda de código dentro del contrato operativo del agente.

Para sesiones de nivel superior, MCP puede funcionar bien porque el agente ve el esquema de la herramienta y llama al servidor directamente. El README de Semble incluye ejemplos de configuración de MCP para Claude Code, Codex, OpenCode, Cursor y otros clientes compatibles con MCP.¹

Para trabajo delegado, el acceso por línea de comandos puede importar más. El README de Semble menciona explícitamente la integración con Bash para subagentes de Claude Code y Codex CLI.¹ Un subagente que no puede acceder a la herramienta MCP de nivel superior aún puede ejecutar un comando de shell si el flujo le enseña cuándo y cómo hacerlo.

Eso significa que la mejor integración puede verse aburrida:

## 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.

Ese tipo de instrucción supera a una regla vaga de “usa búsqueda semántica” porque nombra la decisión de enrutamiento. El agente aprende qué herramienta corresponde a cada pregunta.

Lo que no haría

No reemplazaría rg.

La prueba local lo dejó claro. rg respondió consultas literales en alrededor de una décima de segundo. Semble devolvió mejores paquetes para consultas formuladas como comportamiento, pero mi invocación fría desde la línea de comandos tuvo costos reales de arranque e indexación.⁵

No trataría la afirmación de Semble sobre el 98% de ahorro de tokens como universal. La prueba comparativa compara contra grep más lecturas completas de archivos. La afirmación es razonable cuando esa línea base se parece al comportamiento del agente. Sobrestima la ganancia cuando un flujo disciplinado ya lee rangos de líneas estrechos.

No escondería la decisión de enrutamiento dentro de una caja negra. Los agentes necesitan saber cuándo están haciendo una búsqueda exacta, descubrimiento semántico, exploración de código relacionado o confirmación de evidencia. El uso de herramientas sin reglas de enrutamiento se convierte en otra fuente de fallas plausibles, el mismo problema de interfaz detrás del trabajo de agentes guiado por chat.

Por qué Semble pertenece junto al artículo sobre Grep

El artículo reciente “Is Grep All You Need?” probó grep y recuperación vectorial en Chronos, Claude Code, Codex CLI y Gemini CLI para QA conversacional de memoria larga. El grep integrado superó a la recuperación vectorial integrada en ese contexto, pero la lección más profunda del artículo importa más: el entorno de ejecución cambió el resultado tanto como el método de recuperación.³

Semble apunta a la misma capa operativa desde el lado del código. La calidad de búsqueda no vive solo en el recuperador. Vive en:

• cómo se forma la consulta;
• si existen tanto una ruta exacta como una semántica;
• cuánto contexto devuelve la herramienta;
• si los fragmentos incluyen evidencia de archivo y línea;
• si el agente abre archivos completos solo cuando hace falta;
• si los agentes delegados pueden acceder a la herramienta;
• si la respuesta final cita lo que la búsqueda realmente encontró.

La envoltura sigue siendo el producto. La búsqueda solo se vuelve útil cuando el entorno de ejecución convierte recuperación en evidencia; por eso la superficie de control del diseño agéntico importa tanto como el algoritmo de recuperación.

El estándar que quiero

Una herramienta de búsqueda para agentes debería reportar más que coincidencias.

Debería reportar:

• la consulta que ejecutó;
• la ruta de recuperación que usó;
• el archivo y el rango de líneas;
• el fragmento;
• una estimación de tokens devueltos;
• si el resultado vino de recuperación exacta, semántica o híbrida;
• cuándo el agente escaló de fragmento a lectura de archivo completo.

Esa salida haría auditable la búsqueda de código. Quien revisa podría ver si el agente encontró el código correcto, leyó suficiente contexto y evitó ahogarse en archivos irrelevantes. El mismo principio impulsa las trazas de ejecución de agentes: la prueba vive en el camino, no solo en la respuesta.

Semble ya avanza en esa dirección al tratar el tamaño de los fragmentos y el ahorro de tokens como preocupaciones centrales del producto. El siguiente paso para los entornos de ejecución de agentes es hacer visible ese camino de evidencia en paquetes de revisión y respuestas finales.

El objetivo no es una búsqueda más bonita. El objetivo es tener menos afirmaciones sin respaldo por token.

Preguntas frecuentes

¿Semble reemplaza a grep?

No. Usa rg para cadenas exactas, símbolos, claves de configuración, nombres de archivo y confirmación rápida. Usa recuperación de fragmentos al estilo de Semble cuando la tarea describe comportamiento o implementación relacionada y el agente no conoce el identificador exacto.

¿Tu prueba local confirmó las afirmaciones de velocidad de Semble?

No. Mi invocación local con uvx tardó unos 54 segundos en la primera consulta y 31 segundos en la segunda, sobre todo porque el arranque de paquetes/modelos y la indexación dominaron la ejecución ad hoc. La tabla de pruebas comparativas de Semble informa mediciones controladas mucho más rápidas, pero mi ejecución local debe tratarse como evidencia de flujo de trabajo, no como prueba comparativa de rendimiento.²⁵

¿Tu prueba local confirmó la dirección del ahorro de tokens?

Sí, a nivel de flujo de trabajo. Semble devolvió fragmentos mucho más pequeños que la salida literal amplia de rg, y su comando savings informó unos 38.100 tokens estimados ahorrados después de 2 búsquedas. La cifra de ahorro proviene del propio método contable de Semble, así que trátala como telemetría de la herramienta y no como prueba independiente.⁵

¿Por qué importa la búsqueda de código para agentes en Codex y Claude Code?

Los agentes pierden calidad cuando la búsqueda arroja demasiado contexto u oculta demasiada evidencia. Un buen flujo le enseña al agente cuándo usar búsqueda exacta, cuándo usar recuperación con fragmentos clasificados, cuándo abrir archivos completos y cómo citar el resultado.

¿Los equipos deberían agregar Semble a AGENTS.md?

Solo después de probarlo en su base de código. Empieza con una instrucción: usa búsqueda con fragmentos clasificados para preguntas formuladas como comportamiento y rg para cadenas exactas. Mide si los agentes encuentran los archivos correctos más rápido y leen menos líneas irrelevantes.

Referencias