A busca de código para agentes tem um orçamento de tokens

Semble passou de 900 estrelas no GitHub em 17 de maio de 2026 com uma tese direta: agentes de código desperdiçam boa parte do orçamento de contexto quando usam grep, abrem arquivos inteiros e leem muito mais código do que a tarefa exige.¹

A tese funciona porque muda o enquadramento da busca de código: ela vira um problema de orçamento. Uma pessoa consegue bater o olho em um resultado ruidoso do rg e ignorar o que não importa. Um agente paga por cada linha irrelevante em contexto, atenção e tempo de ciclo de ferramenta.

TL;DR

Semble é uma biblioteca de busca de código para agentes. Ela oferece um servidor MCP, integração com shell por AGENTS.md ou CLAUDE.md, uma CLI e uma API Python.¹ Por baixo, o Semble divide o código em partes, busca com BM25 mais embeddings de código Model2Vec estáticos, combina as listas ranqueadas com Reciprocal Rank Fusion e depois reordena os resultados com sinais específicos de código, como peso de símbolos, reforço para definições, radicais de identificadores, coerência de arquivo e penalidades de ruído.¹ O benchmark informa NDCG@10 de 0,854 em cerca de 1.250 consultas sobre 63 repositórios em 19 linguagens, próximo da pontuação híbrida de 0,862 do CodeRankEmbed, mas com indexação muito mais rápida na tabela do benchmark.² A lição de produto mais importante não é “substitua grep”. É mais precisa: uma ferramenta de busca para agentes deve devolver o menor pacote de evidência que permita ao modelo agir corretamente.

Principais aprendizados

• Para usuários de agentes de código: mantenha rg para strings exatas, mas use busca com snippets ranqueados quando a tarefa pedir comportamento, não um token literal.
• Para criadores de ferramentas: otimize o contexto recuperado, não apenas a precisão da recuperação. A unidade útil é evidência por token.
• Para usuários de Codex e Claude Code: prefira um caminho acessível via shell para subagentes, porque ferramentas MCP de nível superior talvez não cheguem aos agentes delegados da mesma forma.¹
• Para leitores de benchmarks: separe alegações de benchmark do fornecedor do comportamento local em tempo de execução. Minha execução fria com uvx demorou bem mais que a tabela de benchmark do Semble porque a inicialização de pacote, modelo e índice dominou o tempo.
• Para escrita pública: ferramentas de recuperação não eliminam o trabalho de citação. Elas só deixam mais barata a inspeção do caminho até a evidência.

Por que grep continua bom, mas ainda não basta

rg continua sendo a primeira ferramenta certa para strings exatas. Se eu preciso de visible_label_residue, do nome de uma variável de credencial ou de uma função, a busca lexical deve vencer em velocidade e certeza. No meu teste local, uma consulta literal com rg por termos de resíduo de tradução voltou em cerca de um décimo de segundo.⁵

O problema começa quando o agente não sabe a string exata.

Agentes costumam buscar por intenção: “onde a barreira de i18n do blog verifica resíduo em rótulo visível” ou “como funciona a verificação de release de tradução?” A busca literal ainda pode encontrar linhas úteis, mas o agente precisa escolher palavras, inspecionar dezenas de resultados, ler arquivos, reformular a consulta e decidir qual linha contém a resposta. Cada passo consome contexto e cria uma chance de parar cedo demais.

O Semble ataca exatamente esse modo de falha. Ele permite que o agente consulte em linguagem natural e retorna snippets de código ranqueados em vez de arquivos inteiros.¹ Isso não torna rg obsoleto. Muda a interação padrão de “mostre todas as linhas que correspondem a este termo” para “me dê o menor trecho útil de código”.

Essa diferença importa porque agentes não leem como humanos. Pessoas conseguem passar os olhos por 80 linhas de resultado de busca e guardar só as 3 interessantes. Modelos recebem a saída completa como tokens. Um resultado de busca ruidoso passa a fazer parte do ambiente da tarefa.

O que o Semble realmente faz

O README público do Semble descreve quatro caminhos de integração: servidor MCP, Bash / AGENTS.md, CLI e API Python.¹ A configuração para Codex é uma entrada local de servidor MCP em ~/.codex/config.toml, e o caminho via shell adiciona uma seção de busca de código a AGENTS.md ou CLAUDE.md.¹

O caminho via shell importa mais do que parece à primeira vista. O README afirma que subagentes CLI do Claude Code e do Codex devem usar a integração Bash em vez de, ou junto com, MCP, porque subagentes não conseguem chamar ferramentas MCP diretamente nessa configuração.¹ Esse é um ponto prático de interface de agente: a ferramenta de busca precisa existir onde o trabalho acontece, não apenas onde a sessão de nível superior começa.

A pilha de recuperação também parece apontar para onde a busca por agentes está indo:

Esse desenho combina com o que tenho visto em sistemas locais de recuperação: busca puramente vetorial perde identificadores, busca puramente por palavra-chave perde intenção, e ranking híbrido dá ao agente uma primeira leitura melhor.⁴

A alegação do benchmark é sobre contexto, não mágica

O README de benchmark do Semble informa duas classes diferentes de resultado.

A primeira mede qualidade e velocidade de recuperação. A tabela coloca o Semble em 0,854 NDCG@10, CodeRankEmbed Hybrid em 0,862, BM25 em 0,673 e ripgrep em 0,126. O benchmark cobre cerca de 1.250 consultas sobre 63 repositórios em 19 linguagens, com execuções apenas em CPU.²

A segunda mede eficiência de tokens. O benchmark modela um fluxo comum de agentes de código: dividir uma consulta em palavras-chave, executar rg --fixed-strings --ignore-case, ranquear arquivos por correspondências de palavras-chave distintas e então ler por completo os arquivos encontrados. Contra essa linha de base, o benchmark informa uma média de 45.692 tokens para ripgrep mais leitura de arquivos, contra 566 tokens para Semble, uma redução de 98%.²

Essa é a alegação interessante. Não “busca semântica vence grep” em todo cenário. Não “agentes devem parar de usar busca exata”. A alegação é que grep mais leitura envia código irrelevante demais ao modelo quando a tarefa só precisa de alguns trechos.

A metodologia do benchmark também explica onde a alegação se aplica ou não. O Semble compara contra a leitura completa dos arquivos encontrados.² Se o seu fluxo já usa rg -n, sed e intervalos cirúrgicos de linhas, sua linha de base pode ser mais enxuta que o modelo grep mais leitura do benchmark. Se o seu agente abre arquivos inteiros com frequência depois de uma busca ampla, o benchmark se aproxima mais do seu modo real de falha.

Meu teste local

Executei o Semble no repositório do site com uvx --from semble semble e comparei com buscas literais usando rg.

Comecei com uma consulta sobre o processo de release:

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

O Semble retornou cinco snippets. O primeiro resultado resumia o ciclo de release de tradução do blog em uma tabela de um artigo de migração. Outro apontava diretamente para scripts/i18n-automation/README.md, que continha os passos de barreira de qualidade, verificador de release, revisão nativa, commit, push, Railway, Cloudflare e smoke test ao vivo.⁵

O comando rg comparável retornou rápido, mas trouxe um fluxo grande de correspondências literais para variáveis de credencial, blog_release_verify e nomes relacionados em scripts, testes e documentação.⁵ Uma pessoa consegue filtrar isso. Um agente precisa gastar contexto para fazer o mesmo.

Depois perguntei pela implementação da barreira:

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

O primeiro resultado do Semble apontou para o bloco exato da barreira local em que visible_label_residue é atribuído, convertido em erro e usado para afetar o status do achado. A saída incluía as linhas relevantes do corpo da função, em vez de um arquivo inteiro.⁵

A consulta comparável com rg novamente terminou mais rápido, mas retornou muitas ocorrências em testes, prompts de tradução, scripts de reparo, README e na implementação da barreira.⁵

Esse teste não comprova o benchmark do Semble. Minha invocação usou uvx, baixou pacotes e ativos de modelo, indexou um repositório misto grande, incluiu arquivos Markdown e JSON, e rodou por um caminho frio. A primeira consulta do Semble levou cerca de 54 segundos; a segunda, cerca de 31 segundos.⁵ Esses números não batem com a tabela de benchmark do projeto, e eu não os citaria como dados de desempenho do Semble.

O teste comprova o formato do produto. O Semble retornou pacotes de evidência menores e mais próximos de uma resposta. Depois de duas buscas, semble savings --verbose informou cerca de 38.100 tokens estimados economizados, a 94%, usando o próprio método de economia arquivo versus snippet.⁵ Trate isso como uma estimativa da ferramenta, não como medição independente, mas a direção combinou com a saída visível.

O modelo mental certo: pacotes de evidência

Busca para agentes deve produzir pacotes de evidência.

Um pacote de evidência tem quatro propriedades:

rg bruto oferece localização e velocidade. Leituras de arquivo inteiro oferecem contexto, mas contexto demais. Busca vetorial oferece intenção, mas pode perder nomes exatos. Um bom fluxo de busca para agentes combina tudo isso:

1. Use busca exata quando a tarefa nomear um símbolo, erro, chave de configuração, arquivo ou string literal.
2. Use busca semântica ou híbrida com snippets ranqueados quando a tarefa nomear comportamento.
3. Abra o arquivo completo só depois que um snippet provar relevância.
4. Cite o arquivo e o intervalo de linhas na resposta final.
5. Tente de novo com busca exata quando o snippet sugerir um identificador concreto.

O Semble codifica boa parte desse fluxo como ferramenta. O agente ainda precisa de julgamento, e a barreira de evidência ainda precisa de um rastreamento que possa ser inspecionado.

Como o Semble muda fluxos de trabalho no Codex e no Claude Code

A pergunta prática não é se você deve instalar toda nova ferramenta de busca. A pergunta é onde a busca de código entra no contrato operacional do agente.

Para sessões de nível superior, MCP pode funcionar bem porque o agente vê o esquema da ferramenta e chama o servidor diretamente. O README do Semble inclui exemplos de configuração MCP para Claude Code, Codex, OpenCode, Cursor e outros clientes compatíveis com MCP.¹

Para trabalho delegado, acesso via shell pode importar mais. O README do Semble chama explicitamente a integração Bash para subagentes CLI do Claude Code e do Codex.¹ Um subagente que não consegue acessar a ferramenta MCP de nível superior ainda pode executar um comando de shell se o fluxo ensinar quando e como.

Isso significa que a melhor integração pode parecer simples:

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

Esse tipo de instrução vence uma regra vaga como “use busca semântica” porque nomeia a decisão de roteamento. O agente aprende qual ferramenta combina com qual pergunta.

O que eu não faria

Eu não substituiria rg.

O teste local deixou isso claro. rg respondeu consultas literais em cerca de um décimo de segundo. O Semble retornou pacotes melhores para consultas formuladas por comportamento, mas minha invocação fria via shell teve custo real de inicialização e indexação.⁵

Eu não trataria a alegação de 98% de economia de tokens do Semble como universal. O benchmark compara contra grep mais leitura de arquivos inteiros. A alegação é justa quando essa linha de base se parece com o comportamento do agente. A alegação exagera o ganho quando um fluxo disciplinado já lê intervalos estreitos de linhas.

Eu não esconderia a decisão de roteamento dentro de uma caixa-preta. Agentes precisam saber quando estão fazendo consulta exata, descoberta semântica, exploração de código relacionado ou confirmação de evidência. Uso de ferramenta sem regras de roteamento vira mais uma fonte de falha plausível, o mesmo problema de interface por trás do trabalho de agentes guiado por chat.

Por que o Semble pertence ao lado do artigo sobre grep

O artigo recente “Is Grep All You Need?” testou grep e recuperação vetorial em Chronos, Claude Code, Codex CLI e Gemini CLI em perguntas e respostas conversacionais com memória longa. O grep embutido venceu a busca vetorial embutida naquele cenário, mas a lição mais profunda do artigo importa mais: o ambiente de execução alterou o resultado tanto quanto o método de recuperação.³

O Semble aponta para a mesma camada operacional pelo lado do código. A qualidade da busca não vive apenas no recuperador. Ela vive em:

• como a consulta é formada;
• se caminhos exatos e semânticos existem;
• quanto contexto a ferramenta retorna;
• se os snippets trazem evidência de arquivo e linha;
• se o agente abre arquivos inteiros só quando necessário;
• se agentes delegados conseguem acessar a ferramenta;
• se a resposta final cita o que a busca realmente encontrou.

A camada de execução continua sendo o produto. Busca só se torna útil quando o ambiente de execução transforma recuperação em evidência, por isso a superfície de controle do design agentivo importa tanto quanto o algoritmo de recuperação.

O padrão que eu quero

Uma ferramenta de busca para agentes deve informar mais do que correspondências.

Ela deve informar:

• a consulta executada;
• o caminho de recuperação usado;
• o arquivo e o intervalo de linhas;
• o snippet;
• uma estimativa dos tokens retornados;
• se o resultado veio de recuperação exata, semântica ou híbrida;
• quando o agente escalou de snippet para leitura do arquivo completo.

Essa saída tornaria a busca de código auditável. Um revisor conseguiria ver se o agente encontrou o código certo, leu contexto suficiente e evitou se afogar em arquivos irrelevantes. O mesmo princípio orienta os rastreamentos de execução de agentes: a prova vive no caminho, não apenas na resposta.

O Semble já avança nessa direção ao tratar tamanho de snippet e economia de tokens como preocupações centrais do produto. O próximo passo para ambientes de execução de agentes é tornar esse caminho de evidência visível em pacotes de revisão e respostas finais.

O objetivo não é uma busca mais bonita. É ter menos alegações sem sustentação por token.

FAQ

O Semble substitui grep?

Não. Use rg para strings exatas, símbolos, chaves de configuração, nomes de arquivo e confirmação rápida. Use recuperação de snippets no estilo do Semble quando a tarefa descrever comportamento ou implementação relacionada e o agente não souber o identificador exato.

Seu teste local confirmou as alegações de velocidade do Semble?

Não. Minha invocação local com uvx levou cerca de 54 segundos na primeira consulta e 31 segundos na segunda, principalmente porque a inicialização de pacotes/modelos e a indexação dominaram a execução ad hoc. A tabela de benchmark do Semble informa medições controladas muito mais rápidas, mas minha execução local deve ser tratada como evidência de fluxo de trabalho, não como benchmark de desempenho.²⁵

Seu teste local confirmou a direção da economia de tokens?

Sim, no nível do fluxo de trabalho. O Semble retornou snippets muito menores que a saída literal ampla do rg, e o comando savings informou cerca de 38.100 tokens estimados economizados depois de duas buscas. O número de economia vem do próprio método de contabilidade do Semble, então trate como telemetria da ferramenta, não como prova independente.⁵

Por que busca de código para agentes importa para Codex e Claude Code?

Agentes perdem qualidade quando a busca despeja contexto demais ou esconde evidência demais. Um bom fluxo ensina o agente quando usar busca exata, quando usar recuperação com snippets ranqueados, quando abrir arquivos completos e como citar o resultado.

Equipes devem adicionar Semble ao AGENTS.md?

Só depois de testá-lo no próprio código. Comece com uma instrução: use busca com snippets ranqueados para perguntas formuladas por comportamento e rg para strings exatas. Meça se os agentes encontram os arquivos certos mais rápido e leem menos linhas irrelevantes.

Referências