O que é Zvec-Grep (zg)?
O Zvec-Grep, executado como zg, indexa um espaço de trabalho e responde buscas por correspondência exata, ranking de palavras-chave BM25, similaridade vetorial ou um híbrido combinado, devolvendo trechos ranqueados com caminhos, símbolos e números de linha. É construído sobre o banco de dados vetorial zvec e atende tanto uma linha de comando quanto um servidor MCP local. Por padrão os agentes veem uma única ferramenta, zvec_grep_search, pensada para perguntas em que não se sabe o texto exato nem o local; um conjunto completo adiciona rg, gerenciamento de índice e ferramentas de status.
Tem licença Apache-2.0, é publicado no npm como @zvec/zvec-grep e roda em macOS, Linux e Windows. A versão 0.3.0, lançada em 3 de novembro de 2026, reescreveu o núcleo em Rust. O repositório tem cerca de 4.260 estrelas e 92 issues e pull requests abertos, e o pacote no npm teve cerca de 12.189 downloads no último mês.
Como instalar Zvec-Grep (zg)
npm install -g @zvec/zvec-grep --allow-scripts=@zvec/zvec-grep && zg --install --target claudeZvec-Grep (zg) vale a pena?
A escolha de design que importa é a contenção. Enquanto vários servidores concorrentes de contexto de código expõem muitas ferramentas, o conjunto padrão do zg para agentes tem uma, zvec_grep_search, e a documentação orienta o agente a continuar usando o próprio grep para palavras exatas, nomes de arquivo e expressões regulares. A busca combina similaridade vetorial para o significado com BM25 para ancorar identificadores, de modo que uma pergunta como onde as permissões de usuário são verificadas pode chegar à função certa mesmo quando ninguém sabe o nome dela.
Os padrões de privacidade foram bem desenhados. Os índices ficam em .zvec-grep dentro do projeto, os modelos em ~/.zvec-grep/models, e o modelo de embeddings padrão, potion-code-16m-v2, roda localmente; são listados onze modelos locais, do Model2Vec de 16m parâmetros ao Qwen3 Embedding 0.6B em GGUF. Os três modelos remotos do Qwen exigem uma chave de API e, separadamente, uma concessão de consentimento: a chave sozinha não autoriza o envio de conteúdo do espaço de trabalho, o que requer --allow-remote ou uma concessão com escopo de espaço de trabalho. O servidor HTTP opcional escuta em 127.0.0.1:7999 com autenticação desligada por padrão no loopback; um arquivo de token liga a autenticação bearer.
A reescrita em Rust da 0.3.0 é uma mudança grande para um projeto novo. No teste dos próprios mantenedores com 75.128 documentos, o tamanho do pacote caiu de 167,5 MiB para 34,3 MiB, o tempo total de indexação de 219,13 s para 77,84 s, a memória de pico em 53,2% e a latência de busca MCP de 20,93 ms para 14,88 ms. São números do fabricante, assim como os benchmarks A/B de agentes com Claude Code e Codex, e o próprio README diz que os resultados variam conforme o modelo e a execução. Com 92 issues e pull requests abertos e um índice que precisa ser reconstruído sempre que o modelo de embeddings muda, vale testar num repositório antes de virar o padrão da equipe.
Onde ele se destaca
Um desenvolvedor backend recém-chegado a uma base Django de 300.000 linhas
Achar onde uma regra de negócio é aplicada sem saber o nome da função
Rode zg --index uma vez, instale no Claude Code com zg --install --target claude e deixe o agente chamar zvec_grep_search antes de recorrer ao grep. Grátis com modelo local; o tempo de indexação cresce com o tamanho do repositório.
Uma analista de políticas públicas com uma pasta de relatórios e notas
Buscar documentos pelo significado no terminal, sem agente
Indexe com local/potion-retrieval-32m para documentos em inglês e consulte com zg --preview detail. Os resultados vêm ranqueados com referências de arquivo e linha; nada sai do notebook.
Uma equipe de plataforma levando ferramentas de agentes a 20 engenheiros
Dar a todos a mesma busca semântica em editores diferentes
Automatize zg --install para os destinos da equipe (codex, claude, cursor, vscode) e mantenha o conjunto padrão de uma ferramenta. Se quiserem um modelo Qwen compartilhado, concedam embeddings remotos por espaço de trabalho, não globalmente.
Antes de decidir
- Configuração
- npm install -g @zvec/zvec-grep --allow-scripts=@zvec/zvec-grep, depois zg --index no projeto e zg --install --target <cliente>. Reinicie o agente em seguida. O índice fica em .zvec-grep na raiz do projeto.
- Integrações
- Os destinos de instalação incluem codex, claude, qwen, qoder, opencode, cursor, copilot, vscode, grok e pi. MCP por stdio por padrão, ou HTTP via zg --server on. --mcp-toolset full adiciona ferramentas de rg, índice e status.
- Dados e privacidade
- Arquivos, índices e modelos locais ficam na máquina. Embeddings remotos do Qwen enviam conteúdo autorizado do espaço de trabalho e consultas ao provedor só depois de --allow-remote ou de uma concessão de espaço de trabalho, que pode ser revogada.
- Custo em escala
- Grátis com modelos locais. Embeddings remotos do Qwen são cobrados pelo provedor conforme os preços do DashScope, que a documentação do zg não lista.
- Limites
- Só texto, mesmo com modelos de embeddings multimodais. Trocar de modelo ou endpoint exige reconstruir o índice. O servidor HTTP em 127.0.0.1:7999 tem autenticação desligada por padrão no loopback.
O que é bom
- Uma única ferramenta MCP padrão mantém o contexto do agente pequeno
- Modelos de embeddings locais por padrão; nada sai da máquina
- Embeddings remotos exigem concessão explícita de consentimento
- Instalação com um comando para Claude, Codex, Cursor e outros
O que não é
- Os benchmarks são dos próprios mantenedores
- 92 issues e PRs abertos após uma reescrita completa em Rust
- Trocar o modelo de embeddings exige reindexar tudo
- Servidor HTTP local sem autenticação por padrão
Ideal para
Desenvolvedores e pesquisadores que querem que o agente de programação encontre código e documentos pelo significado sem mandar o repositório para uma API de embeddings.
Alternativas ao Zvec-Grep (zg)
Zvec-Grep (zg): perguntas frequentes
- Zvec-Grep (zg) vale a pena?
- Uma ferramenta de busca local bem pensada para agentes, que limita sua superfície MCP a uma ferramenta e torna os embeddings remotos uma escolha explícita, não o padrão. Damos nota 4.0 de 5.
- Quanto custa Zvec-Grep (zg)?
- Gratuito e de código aberto (Apache-2.0). Os modelos de embeddings locais são gratuitos; os embeddings remotos opcionais do Qwen exigem uma chave de API do DashScope e são cobrados por esse provedor.
- Quais são as desvantagens de Zvec-Grep (zg)?
- Os benchmarks são dos próprios mantenedores; 92 issues e PRs abertos após uma reescrita completa em Rust; trocar o modelo de embeddings exige reindexar tudo; servidor HTTP local sem autenticação por padrão.
- Para quem Zvec-Grep (zg) é indicado?
- Desenvolvedores e pesquisadores que querem que o agente de programação encontre código e documentos pelo significado sem mandar o repositório para uma API de embeddings.
- Quanto custa Zvec-Grep (zg) para uma equipe ou em produção?
- Grátis com modelos locais. Embeddings remotos do Qwen são cobrados pelo provedor conforme os preços do DashScope, que a documentação do zg não lista.
- Zvec-Grep (zg) é seguro para dados da empresa?
- Arquivos, índices e modelos locais ficam na máquina. Embeddings remotos do Qwen enviam conteúdo autorizado do espaço de trabalho e consultas ao provedor só depois de --allow-remote ou de uma concessão de espaço de trabalho, que pode ser revogada.
- Quais são as melhores alternativas ao Zvec-Grep (zg)?
- As alternativas mais próximas que analisamos são Serena, CodeGraph, Semble e Project RAG.
Respostas verificadas em 6 de nov. de 2026.
Você faz o Zvec-Grep (zg)? Mostre esta nota no seu site
