jevgrep deixa agentes de código buscarem repositórios por descrição

O que é o jevgrep

O jevgrep é uma ferramenta de linha de comando (CLI) de código aberto, disponível no GitHub sob licença MIT, que permite encontrar código perguntando o que ele faz. O comando jg recebe uma pergunta em linguagem natural sobre um repositório - por exemplo, "como eventos de telemetria são registrados e enviados?" - e retorna arquivos relevantes, pistas de leitura e trechos verbatim do código-fonte em uma única resposta no stdout. A ferramenta usa o Jev para julgar a relevância de pastas, arquivos e declarações, cabendo ao agente de código que a chama as decisões de pesquisa e implementação.

O público-alvo são agentes de código como Claude Code, Codex e OpenCode, que gastam parte de cada tarefa desconhecida localizando os arquivos certos. A instalação requer Node.js 22+, macOS, Linux ou Windows e uma chave de provedor como Vercel AI Gateway, TypeSafe, OpenRouter, OpenCode Zen ou um endpoint compatível com TypeSafe. Não é preciso instalar Python, Bun ou ripgrep separadamente.

Instalação da skill para agentes

Instalar apenas a CLI não ensina o agente de código a usá-la. O projeto exige também a instalação de uma skill, via comando jg skill, que detecta os agentes presentes no projeto e pergunta onde instalar (com opções --global para instalação por usuário e --yes para instalação não assistida). A skill explica invocação e o significado do contexto retornado, mas deixa as decisões de pesquisa e implementação para o agente chamador. Ela verifica se o jg existe e instala a CLI se estiver faltando, embora a autenticação ainda dependa da chave do provedor escolhido - o instalador da skill não configura credenciais.

Como funciona a busca

O jevgrep explora a hierarquia do repositório, segue ramificações qualificadas, seleciona arquivos com base em prévias de conteúdo e identifica unidades de código úteis com contexto ao redor. Ele mantém localizações de arquivos qualificadas mesmo quando não consegue retornar um trecho com confiança, e não força toda busca a uma lista fixa de dois resultados. A saída começa com resumo e lista compacta de arquivos, seguidos do código-fonte selecionado com referências de linha e, depois, localizações detalhadas de declarações e chamadas. Python, TypeScript/JavaScript, Go e Rust têm parsing de declarações; outros textos usam um fallback. A saída é evidência para o agente usar, não uma resposta gerada nem garantia de que todos os arquivos relevantes foram encontrados.

A ferramenta é mais útil para perguntas que abrangem arquivos desconhecidos; quando o símbolo ou caminho exato já é conhecido, uma leitura direta ou busca com rg pode bastar.

O que foi medido

Os autores reportam "mesma inteligência, custo ~30% menor": em uma comparação com dez tarefas ajustadas do SWE-bench, usando um pacote instalado congelado e a skill pública exata do repositório, tanto o jevgrep quanto a linha de base sem Jev resolveram 8 de 10 tarefas. O custo Sol caiu de US$ 7,62 para US$ 5,44 - redução medida de 28,6%, arredondada para ~30% - incluindo tentativas falhas e excluindo o custo do Jev.

Um rerun na versão 0.4.3 com custo total, incluindo o Jev, mediu 25,8% menos custo total com os mesmos 8/10 de tarefas resolvidas. A avaliação da versão 0.5.0 manteve os 8/10 de solves enquanto reduziu o custo nativo do Jev em cerca de 59% em relação àquele rerun; o custo combinado Sol mais Jev ficou 2–3% maior, aceito como um tradeoff pequeno. O próprio README ressalva que são observações de execução única, que não estabelecem equivalência estatística nem ganho de velocidade, e que a comparação mede sucesso de tarefa e custo, não economia garantida em todo repositório.

Privacidade e credenciais

As buscas enviam conteúdo de código elegível ao Jev pelo provedor selecionado na autenticação. A filtragem padrão do sistema de arquivos respeita arquivos de ignore e exclui itens ocultos, dependências/build, binários e arquivos de credenciais óbvios - mas o projeto alerta que esses filtros não garantem que toda informação sensível foi removida, recomendando escolher uma raiz de busca que se pretende enviar. O comando jg files conta os arquivos que uma busca pode ler sem chave de provedor ou requisição de rede, e --exclude aceita padrões gitignore para pular caminhos em uma busca específica.

O jg auth salva a chave em arquivo de configuração restrito ao dono; jg doctor verifica a configuração com entrada sintética. Credenciais baseadas em ambiente e overrides de endpoint não são usados. As respostas de avaliação são cacheadas localmente por padrão, e a CLI escreve apenas no stdout, sem criar arquivos de relatório.

Desenvolvimento e licença

O repositório usa TypeScript, workspaces do Bun e Turborepo, com verificação que inclui testes em Docker do pacote Node instalado. Não há comando jg upgrade; a atualização é feita via npm, e a skill é atualizada separadamente ao rodar jg skill novamente - atualizar o pacote npm não sobrescreve os arquivos da skill nos projetos. O projeto tem 2,4 mil estrelas e 171 forks no GitHub.