O que é o graphify e como ele transforma seu projeto em um grafo de conhecimento?

Fala aí, beleza? Seu assistente de IA abre o projeto, dispara um grep, lê três arquivos e responde com a maior cara de quem entendeu a arquitetura inteira

Só que ele não enxergou o projeto

Ele enxergou os pedaços que a busca por texto devolveu, e o resto ficou no escuro 😀

O graphify é uma skill que ataca exatamente esse ponto: você digita /graphify no assistente e ele transforma o projeto (código, docs, esquemas SQL, configs e PDFs) em um grafo de conhecimento consultável, em vez de varrer arquivos com grep

Ele roda como skill em assistentes como Claude Code, Cursor, Codex e Gemini CLI (a lista não para aí, e mais pra frente você vai ver como ele alcança outras plataformas), e o projeto vive no repositório Graphify-Labs/graphify, sob licença MIT

Neste post te conto o que é o graphify, como ele monta o grafo, o que muda na prática pro seu assistente e como instalar sem cair na pegadinha do nome do pacote

Como o graphify monta o grafo de conhecimento do projeto

Antes do como, o porquê: um projeto não é uma pilha de arquivos soltos, é uma teia

Aquela função chama aquele service, que lê aquela tabela, que está documentada naquele PDF que ninguém abre desde 2024 haha

Formação Recomendada

Formação Vibe Coding

Do Prompt ao Produto: Crie Software Real com IA

• 474 aulas
• 20 projetos
• 39h 27min

Conhecer formação

grep não vê teia, grep vê linha que casa com o texto

Que grafo é esse, afinal? É o desenho dessa teia: cada coisa do projeto vira um nó (arquivo, função, tabela, documento) e cada relação entre elas vira uma aresta que dá pra percorrer

A montagem acontece em duas passagens bem diferentes, e essa distinção importa MUITO:

• Código: parsing determinístico via tree-sitter AST, sem LLM nenhum no meio, nada sai da sua máquina
• Docs, PDFs, imagens e vídeo: aí sim entra uma passagem semântica, usando o modelo do próprio assistente ou uma API key configurada

Ou seja: a parte de código é análise estática pura, previsível, do jeito que um compilador faria

O parsing por tree-sitter cobre 25 linguagens na versão atual do README, entre elas Python, JS, TS, Go, Rust, Java, C, C++, Ruby, C#, Kotlin, Scala, PHP, Swift, Lua, Zig, PowerShell, Elixir, Objective-C, Julia, Verilog, SystemVerilog, Vue, Svelte e Dart

E os esquemas SQL e os configs? Eles estão na lista de coisas que o graphify mapeia, mas o README não diz em qual das duas passagens eles caem, então não vou inventar mecanismo aqui

Cada conexão vem etiquetada:

Esse detalhe é dos mais massa da ferramenta

Cada aresta do grafo é marcada como EXTRACTED, quando a ligação está explícita no código-fonte, ou INFERRED, quando foi o graphify que resolveu aquela ligação

Traduzindo: dá pra saber o que é fato e o que é dedução, sem ter que confiar no chute do assistente

O que sai de uma execução:

Rodou uma vez, ele escreve o diretório graphify-out/ com três arquivos principais:

• graph.html: o grafo interativo pra abrir no navegador
• GRAPH_REPORT.md: um relatório em linguagem simples
• graph.json: o grafo bruto, pronto pra GraphRAG

Tem também uma pasta obsidian/, mas ela só é gerada se você passar a flag --obsidian, então não estranhe a ausência dela

O GRAPH_REPORT.md é o arquivo que eu abriria primeiro: ele destaca os "god nodes" (os nós mais conectados do projeto), as conexões cruzadas surpreendentes entre comunidades e uma lista de perguntas pra explorar

Sabe aquele arquivo que meio mundo importa e ninguém tem coragem de mexer? Ele aparece ali, com nome e sobrenome 😛

Por que um grafo muda a forma de o assistente entender seu projeto

A diferença prática é essa: em vez de varrer arquivos e encher a janela de contexto com texto cru, o assistente percorre arestas

Ele salta de nó em nó seguindo relações que já foram resolvidas antes, na hora de gerar o grafo

O README do projeto publica um benchmark próprio disso: 71,5x menos tokens por consulta em relação a ler os arquivos crus, em um corpus misto de repositórios, papers e imagens

Benchmark de casa, então trate como o que é: número do próprio projeto, medido do jeito do próprio projeto

Ainda assim, a ordem de grandeza faz sentido quando você compara "despejar arquivo inteiro no contexto" com "consultar um grafo"

O mapa é pra ser commitado:

O graphify-out/ foi pensado pra entrar no git

Aí quem faz pull já tem o assistente lendo o GRAPH_REPORT.md direto, sem nenhum passo extra

Isso é bem diferente de um índice que cada dev precisa gerar na própria máquina: aqui o time inteiro começa com o mesmo mapa

E no Claude Code?

Existe um comando de integração específico que instala um hook PreToolUse no .claude/settings.json

Esse hook injeta o lembrete quando o graphify-out/graph.json existe, ou seja: o assistente é cutucado pra consultar o grafo em vez de sair procurando texto na unha

graphify, grep e busca vetorial: qual é a diferença

Gente confunde muito os três, então bora separar

Repara num ponto que costuma passar batido: o graphify não usa embeddings nem vector store

Não é um RAG semântico disfarçado, é um grafo de verdade, com arestas que se percorrem

Para que serve o graphify no dia a dia

Na teoria é bonito, mas cadê o uso real? Se liga nos cenários onde o grafo agrega mesmo:

Entrar em uma base de código desconhecida. Você clona o repo, roda uma vez e lê o GRAPH_REPORT.md pra descobrir quais são os nós mais conectados antes de abrir o primeiro arquivo. É o oposto de sair clicando em pasta aleatória por duas horas

Mapear a ponte entre código e banco. Esquemas SQL estão entre as entradas que o graphify mapeia, então dá pra enxergar quais partes do código estão amarradas em qual tabela

Alinhar o time. Com o graphify-out/ commitado, todo mundo (e todo assistente) parte do mesmo mapa, em vez de cada máquina ter a própria versão da verdade

Alimentar GraphRAG. O graph.json sai pronto pra isso, se você quer construir alguma coisa em cima

Consultar direto pelo terminal. Depois do grafo gerado, o README cita graphify query, graphify path e graphify explain, além da chamada query_graph via MCP

Se a sua ideia é mais organizar documentação e material de apoio do que mapear código, a lógica é parecida com montar uma base de conhecimento no NotebookLM, só que aqui o alvo é a estrutura do projeto em si

Como instalar o graphify e gerar seu primeiro grafo

Bora ver na prática? A instalação recomendada é pelo CLI, em dois tempos: instala o pacote, depois registra a skill no assistente

1. Instale o pacote com o uv

uv tool install graphifyy

Repara no nome: o pacote é graphifyy, com dois "y"

O comando que você chama depois é graphify, com um "y" só. O erro comum deste passo é digitar uv tool install graphify e levar erro de pacote inexistente

2. Registre a skill no seu assistente

graphify install

3. Se você não usa uv, tem alternativa

pipx install graphifyy

ou

pip install graphifyy

4. Se preferir rodar com uvx, nomeie o pacote

uvx --from graphifyy graphify install

O erro comum deste passo é tentar uvx graphify puro: falha, porque o pacote se chama graphifyy e o uvx procura pelo nome do pacote, não pelo do comando. Tome cuidado aqui, é a pegadinha mais boba e a que mais dá dor de cabeça

5. Quer a skill dentro do projeto, e não no seu perfil? Use a flag --project

Com ela a skill é gravada no diretório atual, por exemplo em .claude/skills/graphify/SKILL.md (ou .agents/skills/graphify/SKILL.md no alvo cross-framework)

Bom pra quando o projeto é de time e você quer a configuração versionada junto

6. No Claude Code, rode a integração dedicada

graphify claude install

Esse comando escreve uma seção chamada graphify no CLAUDE.md do projeto, mandando ler o graphify-out/GRAPH_REPORT.md antes de responder sobre arquitetura, e instala o hook PreToolUse no .claude/settings.json

7. Está em uma plataforma sem suporte a hooks? Não tem drama

Aider, OpenClaw, Factory Droid e Trae recebem as mesmas regras gravadas no AGENTS.md da raiz do projeto, justamente porque não suportam hooks de ferramenta

Muda o mecanismo, a instrução continua valendo

8. Gere o grafo

Com a skill registrada, é só digitar /graphify no assistente e deixar rodar

Depois abra o graph.html no navegador e leia o GRAPH_REPORT.md

O hook não dispara no Claude Code: o que aconteceu

Esse aqui é um caso bem didático de como integração quebra sem ninguém mexer em nada

Sintoma: o lembrete simplesmente parou de ser injetado no Claude Code. O grafo estava lá, o graph.json existia, e mesmo assim o assistente voltou a sair procurando arquivo na unha

Causa: o hook usava o matcher Glob|Grep. Só que o Claude Code v2.1.117 removeu as ferramentas dedicadas Grep e Glob nas builds nativas de macOS e Linux, e as buscas passaram a rodar via Bash. Com o matcher esperando ferramentas que não existiam mais, o hook nunca casava e nunca disparava

Solução: a correção trocou o matcher para Bash, casando o comando em si (grep, rg, find, fd), e saiu na v0.5.2 do graphify

Prevenção: mantenha o graphify atualizado. Esse tipo de quebra silenciosa é primo daquela situação de projeto apontando para um modelo aposentado: nada explode, nada grita, a coisa só para de funcionar do jeito que funcionava

Vale a pena usar o graphify no seu projeto?

Veredito honesto: depende do tamanho da bagunça que você tem em mãos

Em projeto pequeno, que cabe inteiro na cabeça e quase inteiro no contexto, o grafo resolve pouco

Agora em base grande, legada, com código, esquema SQL e documentação espalhados, a proposta faz muito sentido: o assistente para de adivinhar por amostragem e passa a percorrer relações que já foram resolvidas antes

Dois pontos pra colocar na balança antes de adotar

O primeiro é que a parte determinística é só o código: docs, PDFs, imagens e vídeo dependem de uma passagem semântica com modelo, então essa fatia tem custo e tem margem de erro

O segundo é que a etiqueta EXTRACTED/INFERRED existe justamente porque nem tudo no grafo é fato duro, e ignorar isso na leitura é pedir pra confiar demais em dedução

Pra dar contexto de tração: o repositório passou de 100 mil estrelas no GitHub (cerca de 108 mil), e a versão mais recente publicada nas releases é a v0.9.47, com o repositório atualizado em 17 de agosto de 2026

Projeto novo, mexendo bastante, então é bom acompanhar as mudanças

O próximo passo prático é curtinho: instala, roda uma vez no seu projeto, abre o graph.html, lê o GRAPH_REPORT.md e, se fizer sentido, commita o graphify-out/ pro time inteiro começar do mesmo mapa

Faça o teste e tira sua própria conclusão, é o tipo de ferramenta que só convence vendo o grafo do SEU projeto na tela

Até o próximo post! =)