Graphify ou grep: qual é a melhor forma de achar as coisas num codebase grande?

O agente dá um grep, volta com 40 arquivos e metade é comentário, teste e uma variável que só tem o mesmo nome do símbolo que você procurava

Fala aí, beleza? O Graphify chegou propondo justamente trocar essa cena: em vez do assistente reler arquivo atrás de arquivo, ele consulta um grafo de conhecimento montado a partir do seu codebase e responde citando arquivo e linha

Só que a pergunta certa aqui não é qual dos dois ganha

A pergunta é o que cada um resolve, e isso a documentação do próprio projeto responde sem enrolação: grep continua imbatível pra string exata

Então bora comparar as duas abordagens de verdade, com os limites que a própria Graphify admite e com os bugs que estão abertos no repositório…

O que é o Graphify e por que ele virou assunto

O Graphify é uma ferramenta open source que transforma um codebase em um grafo de conhecimento consultável

E não é só código: ele também engole docs, schemas SQL, arquivos de config e PDFs, tudo virando parte do mesmo grafo

Esse grafo fica exposto como uma skill /graphify pra Claude Code, Cursor, Codex e Gemini CLI

E como ele monta isso? Parsing AST local com tree-sitter, de forma determinística, sem LLM no meio e sem nada saindo da sua máquina, cobrindo cerca de 40 linguagens

Pré-inscrição Formação Claude Code

Domine o Claude Code do básico ao avançado

Você vai aprender a criar sistemas completos com Claude Code, sem precisar ser programador. Inscreva-se para ter acesso a um desconto de lançamento e bônus especiais!

Quero minha vaga

Repara num detalhe que muita gente passa batido: não tem embeddings, não tem vector store

A ideia é bem diferente da abordagem de jogar tudo num banco vetorial e rezar pra similaridade acertar, que é o caminho mais comum quando você monta um segundo cérebro consultável em cima das suas anotações

Aqui o grafo é estrutural: o que chama o quê, o que depende de quê

Quem está por trás: pela página da Graphify Labs na Y Combinator, o Graphify foi criado por Safi Shamsi, fundador solo da empresa, que fica em Londres e integra o batch Summer 2026 da YC

E a tração que a mesma página lista explica o barulho: mais de 100 mil estrelas no GitHub e mais de 4 milhões de downloads no PyPI em cerca de quatro meses

Número de lançamento é sempre pra se olhar com um pé atrás, mas quatro meses é rápido pra caramba 😀

O que o grep faz no Claude Code hoje

Antes de comparar, vale matar a impressão de que grep é coisa de terminal velho de guerra

A ferramenta Grep do Claude Code é construída sobre o ripgrep, com suporte a regex de verdade e um monte de filtro

Você tem pattern, path, glob, type, -i, -n, -A, -B, -C e ainda o output_mode, que aceita content, files_with_matches e count

Ou seja: dá pra pedir só a contagem, só a lista de arquivos ou o trecho com contexto em volta, sem despejar o repositório inteiro na janela

Tome cuidado com um ponto: o ripgrep normalmente já vem embutido no Claude Code

Quando o binário empacotado não roda no seu sistema, a coisa desanda em silêncio: a busca para de achar arquivo, as menções @file param, subagentes e skills param junto

A saída documentada nesse caso é instalar o ripgrep da sua plataforma e apontar o Claude Code pra ele

Se um dia tudo parecer "vazio" no repo, desconfia disso antes de culpar o modelo

Graphify ou grep: comparativo direto

Repara que não tem uma coluna "vence sempre"

O modelo mental que a própria documentação do Graphify defende é esse: não é substituição, é divisão de trabalho

O agente mantém o grep pras strings e ganha o grafo pra estrutura

Quando usar grep e quando consultar o grafo

Bora ao concreto, com exemplo de pergunta real

O grep vence quando:

• você tem a mensagem de erro literal e quer saber de onde ela sai
• você procura uma chave de config específica
• você quer varrer os TODO do projeto
• você precisa achar todo uso de uma flag depreciada antes de matar ela
• você quer resposta agora, sem construir nada antes

O grafo vence quando:

• a pergunta tem vários saltos ("quem chama isso que chama aquilo que escreve nessa tabela?")
• você quer o caminho entre duas pontas do sistema, e não uma lista de arquivos
• você precisa saber por que um nó importa antes de mexer nele

E o motivo é bem específico: o grep responde só o salto único que dá pra expressar como string

Perguntar "o que chama esta função" devolve todo arquivo que contém aquele nome, incluindo comentário, teste e variável que sombreia o símbolo

Aí o agente ainda precisa ler tudo pra separar sinal de ruído, e é aí que a conta de token estoura

A régua de tamanho: a documentação de how-it-works do projeto explica que o ganho de token cresce com o tamanho do corpus

E a mesma doc diz que, num corpus em torno de seis arquivos, o valor do grafo é clareza estrutural, não compressão

É a mesma lógica de quando você vai otimizar workflows complexos no n8n: a solução que compensa muda conforme o volume, e otimizar cedo demais só te dá trabalho

O que o Graphify devolve na prática

Pra comparação não ficar abstrata, olha o que sai do outro lado

São três comandos de consulta na CLI:

• graphify query responde perguntas sobre a estrutura citando arquivo e linha
• graphify path traça o caminho mais curto entre dois nós, salto a salto
• graphify explain explica por que um nó importa

E cada execução produz três arquivos: um graph.html interativo, um GRAPH_REPORT.md escrito em linguagem simples e um graph.json pronto pra GraphRAG

Tem um detalhe que eu achei mto massa: toda aresta do grafo vem marcada como EXTRACTED (explícita no código-fonte) ou INFERRED (resolvida pelo próprio Graphify)

Ou seja, dá pra auditar o que é fato e o que é dedução da ferramenta, em vez de engolir tudo como verdade

Além da skill, o grafo é servido por um servidor MCP com dez ferramentas que o Claude Code chama nativamente: consultas estruturais, rastreio de caminho e explicação de nós

Como colocar o Graphify no Claude Code

1. Instale via uv, que é o caminho recomendado:

uv tool install graphifyy

O erro comum deste passo: o pacote se chama graphifyy, com dois y, e o comando exposto é graphify

Por isso um uvx graphify simples falha: o uv lê a primeira palavra como nome de pacote, e esse pacote não é o que você quer

2. Registre a skill no assistente:

graphify install

Rodar graphify install sem argumento tem o Claude Code como alvo padrão e registra a skill /graphify

O erro comum deste passo: achar que os outros assistentes entram junto

Não entram, eles precisam ser nomeados explicitamente

3. Se você quiser apertar o parafuso, use a flag --strict:

graphify install --strict

No Claude Code, ela transforma o aviso padrão (consultar o grafo antes de dar grep) em um hook que bloqueia a primeira leitura de arquivo-fonte cru da sessão e redireciona pro grafo, uma vez por sessão

4. Pra manter o grafo vivo conforme o código anda:

graphify hook install

Pela documentação de instalação, esse comando embute o caminho do interpretador atual dentro dos scripts de hook no momento da instalação, pro hook de post-commit disparar mesmo em cliente git gráfico e em runner de CI, onde ~/.local/bin não está no PATH

O erro comum deste passo: esquecer dele depois de um upgrade

Depois de reinstalar ou atualizar o Graphify, você precisa rodar graphify hook install de novo

Veredito: o grafo não aposenta o grep

Começando pelo que pesa a favor: o benchmark oficial do projeto mede 71,5x menos tokens por consulta contra a leitura direta dos arquivos, num corpus misto de 52 arquivos (repositórios do Karpathy, 5 papers e 4 imagens)

E, pelo menos, é um benchmark que não fica só no slide: o repo publica as pastas worked/ com entradas e saídas pra reprodução, e imprime um benchmark de tokens depois de cada execução

Agora o outro lado, e aqui a própria Graphify é honesta na doc: o grafo é um snapshot, precisa ser reconstruído quando o código muda de forma relevante, leva minutos pra ser construído e vira overhead desnecessário se todas as suas perguntas forem busca de string de um salto só

E tem os relatos abertos no repositório, que valem mais que qualquer promessa:

• issue #580: usuário que não viu ganho de token no Claude Code, porque o agente responde que vai ler o grafo primeiro e consulta o GRAPH_REPORT, e cada invocação da CLI de query consome cerca de 2 mil tokens, chegando a mais de 8 mil quando o agente chama 3 ou 4 vezes num mesmo fluxo
• issue #1116: símbolos removidos de arquivos que continuam existindo não são podados e sobrevivem a todo rebuild incremental, até uma reconstrução limpa
• issue #857: o graphify extract pode pular silenciosamente arquivos semanticamente desatualizados por causa do manifest.json compartilhado com o graphify update

Juntando tudo: ganha quem tem repositório grande, faz pergunta de vários saltos o dia inteiro e vive queimando contexto com o agente relendo arquivo pra separar ruído

Não ganha quem tem projeto pequeno, pergunta quase sempre por string exata e não quer administrar rebuild de grafo

E, pra fluxo crítico, os bugs de atualização incremental pedem cautela: grafo desatualizado responde com confiança sobre código que não existe mais

Conclusão

A resposta pra "Graphify ou grep" é chata de tão simples: grep pra string, grafo pra estrutura, e o agente usando os dois

O próximo passo concreto é este, e dá pra fazer hoje: escolhe três perguntas reais do seu repo, duas de string exata e uma de vários saltos, e vê qual caminho responde mais rápido ANTES de montar qualquer grafo

Se as três forem de string, você acabou de economizar alguns minutos de build e um monte de manutenção

E lembra que a ferramenta é jovem, com bugs abertos de atualização incremental, então vale acompanhar o repositório antes de colocar o grafo no meio de um fluxo crítico

Fez o teste? Conta aí nos comentários qual dos dois respondeu melhor no seu codebase, até o próximo post!