O que é o Graphify e como ele muda a forma como o Claude Code entende seu projeto?

Fala aí, beleza? Tem um gargalo no Claude Code que nenhum prompt bonitinho resolve: em projeto grande, o assistente abre arquivo por arquivo e remonta o entendimento do zero a cada sessão nova

E você paga esse pedágio toda santa vez… o mesmo tour pelas mesmas pastas, só pra ele descobrir de novo quem chama quem 😅

O Graphify aparece bem nesse ponto. A proposta é trocar leitura crua de arquivo por um mapa consultável: uma pasta com código, docs, schemas SQL, configs, PDFs e imagens vira um grafo de conhecimento que o assistente consulta em vez de varrer o repositório inteiro. É open source, faz parsing AST local determinístico, não usa vector store e chega como skill /graphify para Claude Code, Cursor, Codex e Gemini CLI

Que problema de contexto o Graphify ataca

A ideia de fundo não é nova. O conceito de base de conhecimento pessoal (o tal LLM wiki) foi popularizado pelo Andrej Karpathy: em vez do modelo redescobrir tudo, ele lê uma base já organizada sobre o teu material

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

O Graphify parte desse conceito e faz uma troca: sai o wiki plano, entra um grafo

Por que isso muda algo? Um wiki é texto atrás de texto, e o assistente ainda precisa caçar a relação entre as coisas. Um grafo já guarda a relação: essa função chama aquela, esse arquivo importa aquele módulo, essa tabela referencia aquela outra

E agora o ponto que mais confunde quem só ouviu o nome: o Graphify NÃO é um projeto do Karpathy. A relação é de inspiração, não de autoria

A ferramenta foi criada por Safi Shamsi, fundador da Graphify Labs, empresa da batch YC S26, sediada em Londres. O repositório oficial vive em Graphify-Labs/graphify (a URL antiga github.com/safishamsi/graphify aponta pro mesmo projeto), e a documentação fica em graphify.com

Se alguém te mandar um post dizendo que é "o projeto novo do Karpathy", já sabe: tá errado

Como o Graphify monta o grafo do seu projeto

Aqui mora a parte mais interessante da engenharia, e ela é mais simples do que parece

O Graphify roda em passadas distintas, cada uma com um trabalho diferente

A primeira passada é determinística: usa tree-sitter pra extrair a estrutura do código (classes, funções, imports, grafo de chamadas e docstrings) localmente, sem LLM nenhum no meio

Se você conhece um linter ou um parser de IDE, é o mesmo espírito: ler a árvore sintática do arquivo e tirar dali o que existe de fato, não o que um modelo achou que existe

A passada semântica, essa sim com LLM, fica reservada pro que não tem sintaxe formal: docs, papers, imagens e transcrições. No pipeline normal, arquivos de código não são enviados pro extrator semântico

Desde a versão 0.6.0 o SQL também entra pelo caminho determinístico via tree-sitter, e o mapeamento é bem direto:

Ou seja: o schema do teu banco vira parte do mesmo mapa que o código, com as ligações de FK desenhadas

E tem uma consequência prática MUITO massa disso tudo: se o teu corpus é só código, o graphify extract roda totalmente offline, sem chave de API, porque a passada semântica é simplesmente pulada

Sem chave, sem custo de token pra montar o mapa

O que muda no dia a dia de quem usa Claude Code

Beleza, mas na prática, dentro da sessão, o que muda?

O comando graphify install registra a skill criando o arquivo ~/.claude/skills/graphify/SKILL.md. Se você já mexeu com skills que ampliam o Claude Code, o formato é familiar: um arquivo de instrução que o assistente carrega e passa a seguir

Na instalação padrão, essa skill sugere que o assistente rode graphify query antes de sair lendo arquivo

Sugestão é sugestão, né? Às vezes ele segue, às vezes ele volta pro velho hábito de abrir o arquivo direto

Por isso existe o modo estrito, com graphify install --project --strict. Nele, a primeira leitura crua de arquivo da sessão é bloqueada e redirecionada pro grafo, e depois disso a coisa volta pro modo de sugestão

É um empurrão pra sessão começar pelo mapa em vez de começar pelo tour

Outro detalhe que agrada quem já vive dentro do Claude Code: para execução headless, o Graphify aceita vários backends de LLM detectados por variável de ambiente (GEMINI_API_KEY/GOOGLE_API_KEY, MOONSHOT_API_KEY, ANTHROPIC_API_KEY, OPENAI_API_KEY, DEEPSEEK_API_KEY, Ollama via OLLAMA_BASE_URL, Bedrock via credenciais AWS) ou então o binário claude do próprio Claude Code

Essa última opção usa a assinatura que você já tem e não pede chave de API

E tem um cuidado bem-vindo no graphify query: ele informa, logo no início da resposta, qual grafo foi aberto e quantos nós ele tem

Parece bobo, mas evita o pesadelo clássico de rodar a consulta a partir de um projeto pai e receber resposta sobre o corpus errado, sem perceber. Tome cuidado com isso quando tiver monorepo com vários grafos por perto!

O que o Graphify entrega no final: os arquivos em graphify-out/

O resultado não é uma caixa preta, e isso ajuda bastante a confiar (ou desconfiar) da ferramenta

A saída é gravada na pasta graphify-out/, dentro do diretório analisado, com quatro coisas:

• graphify-out/graph.html: o grafo interativo, pra você olhar com olho humano mesmo
• graphify-out/GRAPH_REPORT.md: um relatório de arquitetura
• graphify-out/graph.json: o grafo legível por máquina, no formato node-link do NetworkX
• graphify-out/cache/: o cache da extração

O graph.html é o teste rápido de sanidade: se o desenho não se parece com o teu projeto, o mapa não vai ajudar o assistente também

E aqui vem o ponto que interessa a quem trabalha em time: a pasta graphify-out foi pensada pra ser commitada

Ou seja, quem der pull recebe o mapa pronto, sem precisar reconstruir nada na máquina dele

O dev novo do time clona o repo e já chega com o mapa na mão, sabe? 😀

Como instalar e usar o Graphify no Claude Code

A sequência mínima é curta, mas tem uma pegadinha logo no primeiro passo

1. Instale o CLI. O caminho recomendado é o uv:

uv tool install graphifyy

Alternativas: pipx install graphifyy ou pip install graphifyy (nesse último, pode ser preciso ajustar o PATH pro comando ficar disponível)

2. Atenção ao nome do pacote, que é O erro comum deste passo: no PyPI o pacote se chama graphifyy, com dois y, enquanto o comando instalado é graphify. Outros pacotes graphify* no PyPI não são do projeto

Digitou um y só? Você instalou outra coisa

3. Registre a skill. Rodado sem flag nenhuma, o comando abaixo registra no Claude Code:

graphify install

Isso cria o arquivo ~/.claude/skills/graphify/SKILL.md, valendo pro teu perfil de usuário

4. Se você prefere instalar no repositório atual em vez do perfil, use a flag --project:

graphify install --project

Aí o arquivo vai pra .claude/skills/graphify/SKILL.md dentro do projeto

5. Usa outro assistente? Cada plataforma suportada tem subcomando próprio, ou você resolve na flag --platform:

graphify cursor install
graphify codex install
graphify gemini install
graphify install --platform codex

6. Com tudo instalado, o uso dentro de uma sessão do Claude Code é digitar:

/graphify .

O ponto ali é o diretório que você quer analisar

A doc oficial dos passos de instalação fica em graphify.com/docs/install, vale conferir antes de rodar

Mantendo o grafo atualizado: hook de commit e /graphify –update

Mapa desatualizado é pior que mapa nenhum, então essa parte importa

São duas frentes, e elas se dividem exatamente como as passadas que vimos lá em cima: código de um lado, docs e papers do outro

Código: o hook post-commit

O comando graphify hook install coloca um hook post-commit que reconstrói o grafo a cada commit usando só a passada AST, ou seja, sem custo de API

E ele configura também um merge driver do git para o graph.json, o que evita aqueles marcadores de conflito quando duas pessoas commitam em paralelo

Se você já anda deixando o assistente mexer no fluxo de commits do repositório, esse encaixe é natural: o grafo se atualiza no mesmo momento em que o código muda

Alerta operacional pra guardar: se você reinstalar ou atualizar o graphify, rode graphify hook install de novo

O motivo é que o caminho do interpretador fica embutido nos scripts do hook no momento da instalação. Trocou o interpretador de lugar, o hook aponta pro vazio

Docs e papers: o /graphify --update

Agora a outra frente. O hook cobre mudança de código, e só

Docs, papers, imagens e transcrições são justamente os nós que passam pela extração semântica, aquela com LLM. Esses não se atualizam sozinhos no commit

Então, quando um documento ou um paper mudar, quem atualiza esses nós é o comando, digitado dentro da sessão do assistente:

/graphify --update

Resumindo a divisão pra não confundir: código se atualiza sozinho no commit, via hook, e docs e papers você atualiza na mão com o /graphify --update

Licença e maturidade do projeto

O Graphify ainda está na faixa do 0.x, e isso já diz bastante sobre o estágio

A versão 0.9.25 foi publicada em 22 de julho de 2026, e nela aconteceu uma mudança que passa despercebida por dev, mas não passa por jurídico: o projeto trocou a licença MIT pela Apache License 2.0

Qual a diferença que pega? A Apache 2.0 traz concessão explícita de patente e cláusula de retaliação de patente, coisa que a MIT não tem

Na prática, pra quem pensa em adotar dentro de empresa, isso costuma facilitar a vida: a permissão de patente vem escrita, em vez de ficar no campo do "provavelmente tá tudo bem"

Se o teu time tem processo de aprovação de open source, esse é o dado que a pessoa do outro lado vai querer ver

Vale a pena colocar o Graphify no seu fluxo?

Vou ser honesto com você: é lançamento recente, eu não rodei aqui em projeto de verdade ainda, então não vou cravar recomendação nem sair chamando de topzera sem prova

O que dá pra dizer com segurança é que a ideia ataca um problema real, e ataca por um caminho verificável: estrutura de código saindo de parser determinístico, não de chute de modelo

Se você quiser tirar a prova, o caminho de menor risco é bem direto

Pega um repositório só de código (que, lembra, dispensa chave de API porque a extração roda offline), roda o /graphify . e abre duas coisas: o graph.html e o GRAPH_REPORT.md

Aí faz a pergunta que interessa: esse mapa bate com o projeto real? Os módulos importantes estão lá? As ligações fazem sentido?

Se bater, aí sim faz sentido pensar no modo estrito e no hook de commit. Se não bater, você descobriu isso em cinco minutos e sem gastar token 😉

Bora testar e depois trocar uma ideia sobre o resultado?

até o próximo post!