Agentes de programação gastam uma fatia grande do seu orçamento de ferramentas com busca. Quando o alvo é um símbolo conhecido, o ripgrep resolve com precisão. Quando o alvo é um comportamento descrito em linguagem natural, a busca por palavra-chave costuma falhar — e o agente recorre a chutes de termos, leitura de arquivos inteiros e montagem manual de contexto. Cada um desses desvios custa chamadas de ferramenta, tokens e tempo de execução.
Para atacar exatamente esse gargalo, a equipe do Qwen anunciou o zg (zvec-grep): uma camada de busca local-first e de código aberto que coloca busca semântica, BM25 e ripgrep atrás de uma única interface, tanto para humanos quanto para agentes. O código está sob a organização zvec-ai no GitHub, com licença Apache 2.0.
O que o zg entrega na prática
É instalável hoje: vem do npm como @zvec/zvec-grep, exige Node.js 22 ou superior em macOS, Linux ou Windows, não precisa de GPU com o modelo padrão e a licença Apache 2.0 permite uso comercial.
O zg indexa o workspace uma única vez e expõe quatro rotas de recuperação:
- Híbrida (padrão): combina intenção semântica com âncoras lexicais.
--fts: BM25 com termos exatos, ranqueado por relevância léxica.--vector: similaridade conceitual, sem ranqueamento léxico.--rg: correspondência literal ou regex exaustiva — e, importante, não precisa de índice, o que ajuda quando o repositório ainda não foi indexado.
O índice fica em <root>/.zvec-grep/. Os diretórios .git e .zvec-grep são sempre excluídos, junto com dependências, build, cache e logs comuns, além de tudo que as regras de ignore do próprio repositório excluírem. Reexecutar zg index atualiza de forma incremental; trocar o modelo de embedding exige --rebuild explícito, já que espaços vetoriais de modelos diferentes são incompatíveis mesmo em dimensões iguais.
Integração com agentes via MCP
O zg install detecta Codex, Claude Code, Cursor e OpenCode na máquina e configura a integração MCP local. O servidor fala Streamable HTTP MCP em um endpoint restrito ao loopback (http://127.0.0.1:7999/mcp), com autenticação bearer opcional.
A decisão de design que chama atenção é a contenção: o conjunto padrão de ferramentas expõe apenas duas — zvec_grep_search (quando a intenção é conhecida mas a string exata não) e zvec_grep_rg (quando um símbolo, caminho ou regex é conhecido). O ciclo de vida do índice fica com a CLI. Um conjunto de compatibilidade com seis ferramentas existe, mas é opt-in via --mcp-toolset full, e a documentação é explícita: um agente nunca deve criar, reconstruir ou apagar silenciosamente um índice persistente.
A saída é moldada para economia de contexto: resultados vêm agrupados por arquivo, com intervalos de linha, e prévias de código são omitidas por padrão. O zg ainda rejeita flags do ripgrep que mudam a saída (como --json, --count, -l e --vimgrep) para manter o formato compacto.
Embeddings rodam no dispositivo
O catálogo documenta dez modelos locais e três endpoints remotos do Qwen. O padrão do quickstart, local/potion-code-16m-v2, é um modelo estático Model2Vec com saída de 256 dimensões e limite de 8.192 tokens de entrada. Por usar lookup vetorial estático, selecionar GPU não acelera. Opções locais mais pesadas incluem jina-embeddings-v2-base-code, embeddinggemma-300m e qwen3-embedding-0.6b. No lado remoto, há modelos como o qwen/qwen3.7-text-embedding (128 mil tokens de entrada) e o multimodal qwen/qwen3-vl-embedding.
O uso remoto é restrito por padrão: configurar uma credencial de provedor não autoriza a transferência de dados. É preciso --allow-remote em um comando específico ou uma concessão assinada do workspace via zg auth grant (revogável com zg auth revoke).
Os números dos benchmarks
Os resultados de avaliação aparecem no post de lançamento — no repositório, a seção de benchmarks ainda é um placeholder. Os dois testes foram A/B pareados, mantendo agente, modelo, prompt, runtime e restrições de tarefa fixos; a condição zg apenas adicionava índice pré-construído, ferramentas MCP e orientação de uso. O custo de construção do índice fica fora das tabelas.
Numa amostra de 20 perguntas do SWE-QA-Bench, o zg cortou as chamadas de ferramenta em mais da metade e os tokens de entrada em quase metade, elevando o score Judge em 1,50 ponto. Numa amostra de 80 perguntas do BrowseComp-Plus, a acurácia subiu de 98,67% para 99,00%, enquanto os tokens de entrada caíram 37,56%, as chamadas de ferramenta 43,52% e o tempo do agente 38,58%. Separadamente, indexar o repositório do Django (3.457 arquivos) é reportado como terminando em menos de 30 segundos num Apple M4 Pro.
Vale o alerta editorial: amostras de 20 e 80 perguntas são pequenas, e as reduções vêm de testes do próprio fornecedor — a replicação independente é o próximo passo óbvio antes de tratar os números como consenso.
Por que isso importa para desenvolvedores brasileiros
Para quem trabalha com agentes de código — ou mantém repositórios grandes — o zg ataca um custo real e frequentemente invisível: o desperdício de tokens e chamadas de ferramenta em busca ineficiente. Por ser local-first, roda sem enviar código para a nuvem, o que é relevante em cenários com dados sensíveis ou restrições de conformidade. E, por ser Apache 2.0 e instalar via npm, entra sem fricção em fluxos já estabelecidos com Claude Code, Cursor ou Codex.
Ainda é um projeto jovem, com benchmarks a serem validados de forma independente e alguma documentação em construção. Mas a direção — consolidar busca semântica, léxica e por regex num único índice local, com superfície mínima para agentes — é um sinal claro de onde a ferramenta de agentes está evoluindo.
Descubra mais sobre noticiAI
Assine para receber nossas notícias mais recentes por e-mail.
