Como usar o Graphify no Claude Code: instalação, primeiro comando e o primeiro mapa do seu código

Abrir um repositório gigante que você nunca viu é tipo chegar numa cidade nova sem GPS, sem placa e sem ninguém pra perguntar

Fala aí, beleza? Apareceu uma ferramenta que ataca exatamente essa dor: o Graphify, uma skill /graphify que pega uma pasta de código e devolve um grafo de conhecimento consultável dentro do próprio Claude Code

Aqui eu vou cobrir só o caminho que dá pra verificar na documentação: instalar o pacote, registrar a skill no assistente e rodar o primeiro mapa

Nada de passo inventado, nada de configuração que você não vai encontrar na tela…

O que é o Graphify e por que ele não pede conta nem chave de API

O Graphify é um pacote Python publicado no PyPI com o nome graphifyy, e ele se descreve como skill para assistentes de código: Claude Code, Codex, OpenCode, Cursor, Gemini CLI, Aider e outros

A função dele é transformar uma pasta (código, docs, papers, imagens ou vídeos) em um grafo de conhecimento que você consulta

Que grafo de conhecimento? Em vez de jogar o repo inteiro na janela de contexto e torcer, a ferramenta faz o parsing dos arquivos, extrai os nós (arquivos, funções, conceitos) e as relações entre eles, e agrupa isso em comunidades

O parsing roda com tree-sitter, no seu dispositivo, cobrindo 36 linguagens de código, mais Markdown, SQL e outros formatos

Se você conhece aquele diagrama de arquitetura que ninguém atualiza há dois anos, pensa nele sendo gerado direto do código, e não da memória do time

E aqui vem a parte que mais me chamou atenção: não tem conta e não tem chave de API

O grafo estrutural é feito por parsing local, e a passagem semântica roda pela própria sessão do assistente que você já usa

Ou seja: sem cadastro, sem mais um painel de billing pra você administrar

O parsing AST é local e determinístico, sem vector store, segundo o repositório oficial no GitHub, mantido sob a organização Graphify-Labs

O que você precisa antes de instalar o Graphify

A lista de pré-requisitos declarada na documentação é curtinha:

• Python 3.10 ou superior (esse é o mínimo pra instalar)
• Um repositório pra mapear (pode ser o seu, pode ser um clone de projeto alheio)
• Um assistente de código compatível, que neste tutorial é o Claude Code

Se o Claude Code ainda não está na sua máquina, vale ver antes os primeiros passos com o Claude Code, porque o Graphify entra depois: ele é uma skill que vive dentro do assistente, não um substituto dele

Tome cuidado com o nome do pacote! O comando que fica no seu terminal é graphify, mas o pacote que você instala é graphifyy, com dois ‘y’

Existem outros pacotes de nome parecido no PyPI que não são o projeto oficial e não têm afiliação nenhuma com ele

Então o nome exato faz parte do passo de instalação, não é detalhe estético 🙂

Passo a passo: do primeiro comando ao primeiro mapa

Bora ver na prática?

1. Instale o pacote oficial

A forma recomendada usa uv:

uv tool install graphifyy

Se você prefere pipx ou pip, as alternativas são estas:

pipx install graphifyy
pip install graphifyy

O erro comum deste passo: digitar graphify no lugar de graphifyy e acabar instalando um homônimo do PyPI que não é o projeto

2. Confira se o comando graphify está no PATH

Instalado via uv tool install ou pipx install, o comando fica no diretório bin de ferramentas, o ~/.local/bin

Se o shell não achar o comando logo depois de instalar, roda isso:

uv tool update-shell
# ou, se você usou pipx:
pipx ensurepath

Depois abre um terminal NOVO

O erro comum deste passo: rodar o update-shell e continuar tentando na mesma janela, que ainda está com o PATH antigo carregado

3. Registre a skill no assistente

Esse comando de terminal copia a skill /graphify pra configuração do assistente (ele registra, ele não gera mapa nenhum ainda):

graphify install

Sem argumento nenhum, o alvo padrão por design é o Claude Code (e o Windows é detectado automaticamente)

Qualquer outro assistente precisa ser nomeado explicitamente

Se você gosta de ser explícito, existe a forma por plataforma:

graphify claude install

Uma nota importante pra quem mexeu na configuração do Claude: no modo always-on, o registro é escrito no CLAUDE.md dentro de $CLAUDE_CONFIG_DIR quando essa variável de ambiente realoca o perfil, em vez de sempre mexer no ~/.claude/CLAUDE.md padrão

O erro comum deste passo: pular ele achando que instalar o pacote já basta

4. Rode o primeiro mapa dentro do Claude Code

Agora sim vem o comando que gera o grafo, e ele NÃO é de terminal: abre o assistente na pasta do projeto e chama a skill com barra

/graphify .

O ponto ali é a pasta atual

Repara na diferença, porque ela confunde muita gente: graphify install você digita no terminal, /graphify . você digita dentro do Claude Code

Se essa é a sua primeira vez chamando algo dentro do assistente, dá uma olhada em o que acontece no primeiro comando pra não estranhar o fluxo

Na execução, o Graphify faz o parsing com tree-sitter, extrai nós e relações, agrupa em comunidades e escreve tudo na pasta graphify-out/

5. Abra a saída

A primeira execução gera três arquivos principais:

• graphify-out/graph.html
• graphify-out/GRAPH_REPORT.md
• graphify-out/graph.json

O graph.html é o grafo interativo e abre em qualquer navegador

O GRAPH_REPORT.md é o relatório de arquitetura, com os conceitos-chave do projeto e perguntas sugeridas

E o graph.json é o grafo completo legível por máquina, pra quando você quiser processar aquilo com script próprio

6. Opcional: ligue o hook de commit

Mapa desatualizado é pior que mapa nenhum, então existe isso aqui:

graphify hook install
graphify hook status

O hook install reconstrói o grafo depois de cada commit, pra manter o mapa acompanhando o código

E o hook status serve pra conferir se ele está mesmo ativo

Erros comuns na primeira instalação (e como evitar)

O terminal diz que o comando graphify não existe

Causa: o diretório de ferramentas (~/.local/bin) não está no PATH do seu shell

Solução: rodar uv tool update-shell (ou pipx ensurepath, se foi por pipx) e abrir um terminal novo

Como prevenir: já assuma que o primeiro terminal depois da instalação está "velho" e abra outro antes de testar

Você instalou e nada se parece com a documentação

Causa: foi instalado um pacote de nome parecido, e não o oficial

Solução: instalar pelo nome exato, graphifyy, com dois ‘y’

Como prevenir: copiar e colar o nome do pacote em vez de digitar de cabeça, porque a diferença é uma letra só

A skill /graphify não aparece dentro do assistente

Causa: o pacote foi instalado, mas o passo de registro não rodou

Solução: rodar graphify install no terminal (ou graphify claude install, na forma explícita)

Como prevenir: tratar instalação e registro como duas etapas diferentes, porque é isso que elas são

O que fazer com o primeiro mapa: como ler a saída do Graphify

Gerar o grafo é a parte fácil, o valor aparece em COMO você lê ele

O caminho mais rápido é abrir o GRAPH_REPORT.md e começar pelas perguntas sugeridas, junto dos conceitos-chave que ele lista

É o atalho pra entrar num repo desconhecido sem ficar rolando pasta por pasta no escuro

Depois vem a parte que separa ferramenta séria de chute bonito: as respostas vêm com caminhos explícitos e citações no formato arquivo:linha

Ou seja, dá pra abrir o arquivo e conferir se a afirmação se sustenta

E cada aresta do grafo vem marcada, indicando o quanto aquela ligação está ancorada no código:

Esse rótulo é o seu medidor de confiança

O que está como EXTRACTED você trata como base, o que está como INFERRED ou AMBIGUOUS você trata como pista a conferir, nunca como verdade

É a diferença entre um mapa que te ajuda e um mapa que te empurra pro barranco 😀

Próximo passo depois do primeiro grafo

O próximo passo concreto é este: rode o /graphify . primeiro num projeto que você já conhece de cor, e só depois no repo estranho

Assim você calibra a leitura do grafo comparando com o que já sabe, e chega no código desconhecido sabendo em quanto confiar em cada rótulo de aresta

Depois disso, liga o graphify hook install pra o mapa não envelhecer junto com o código

Recapitulando o caminho todo: instalar graphifyy com uv, pipx ou pip, garantir o comando graphify no PATH, registrar a skill rodando graphify install no terminal e, aí sim, chamar /graphify . dentro do Claude Code

A saída aparece em graphify-out/, com o grafo em HTML, o relatório em Markdown e o JSON completo

Qualquer coisa além disso (número de versão, licença, economia de token) eu deixo de fora aqui, porque não achei fonte que se sustente, e achismo de número é coisa que eu não escrevo

Bora testar e me conta o que o teu grafo mostrou

Até o próximo post!