graphify na prática: transforme qualquer repositório de código em um grafo de conhecimento pesquisável

Dificuldade média | Cerca de 20 minutos | Você vai dominar o fluxo completo de como usar o graphify para converter qualquer repositório de código em um grafo de conhecimento pesquisável, deixando de fazer grep às cegas e alcançando uma compreensão de código estruturada com compressão de 71,5x de tokens.

Visão geral do projeto

graphify é uma skill de assistente de codificação por IA (skill), desenvolvida por Safi Shamsi, com endereço no GitHub safishamsi/graphify. A proposta é simples: compactar qualquer pasta (código, anotações, artigos, imagens e até vídeos) em um único grafo de conhecimento pesquisável, para que cada conversa com seu assistente de IA se baseie em conhecimento estruturado — e não em correspondências cegas de texto.

Os destaques estão em três pontos:

• Entrada multimodal: código (20 linguagens), documentos, imagens, PDFs e áudio/vídeo são suportados, tudo unificado na mesma estrutura de grafo
• Sem clusterização por embeddings: usa o algoritmo de detecção de comunidades Leiden para agrupar diretamente com base na topologia do grafo, sem precisar de banco vetorial e sem rodar um modelo de embeddings separadamente
• Confiança honesta: cada aresta de relação é marcada como EXTRACTED / INFERRED / AMBIGUOUS; você sabe o que foi encontrado e o que foi inferido

graphify pode ser usado via o comando /graphify por assistentes de codificação populares como Claude Code, OpenClaw, Codex, Cursor, Trae etc., ou ainda pode ser chamado de forma independente via um MCP Server ou pela CLI.

Público-alvo

Você já trabalhou em pelo menos um projeto de porte médio (mais de mil linhas de código) e, no dia a dia, usa Claude Code / OpenClaw / Codex ou outros assistentes de codificação por IA. Quando enfrenta um novo repositório, você costuma pedir para ele ler o código diretamente — mas, conforme os arquivos aumentam, começam a ficar cada vez mais evidentes problemas como alto consumo de tokens e contexto fragmentado. Este artigo existe para resolver exatamente isso.

Dependências essenciais e ambiente

Estrutura completa do projeto

my-project/
├── graphify-out/
│   ├── graph.json          # Grafo persistente de conhecimento, consultável entre sessões
│   ├── GRAPH_REPORT.md     # Relatório de análise estruturada (god nodes, conexões inesperadas, questões sugeridas)
│   ├── graph.html          # Grafo interativo (vis.js, abra direto no navegador)
│   ├── cache/              # Diretório de cache SHA256
│   └── transcripts/        # Cache de transcrição de áudio/vídeo (só funciona se instalar a dependência de video)
├── .graphifyignore         # Regras de exclusão (sintaxe igual à de .gitignore)
└── .git/hooks/            # Gerado automaticamente após instalar o hook do graphify

Passo a passo

Passo 1 — Instalar graphify

graphify tem duas etapas: instalar o pacote Python e instalar a camada de adaptação para o seu assistente de codificação por IA.

# Primeira etapa: instalar o pacote do PyPI
pip install graphifyy

# Segunda etapa: instalar a camada de adaptação para a sua plataforma
# Exemplo com Claude Code:
graphify install

# Se for outra plataforma, use o comando correspondente:
# graphify install --platform codex
# graphify install --platform opencode
# graphify install --platform claw        # OpenClaw
# graphify install --platform aider
# graphify install --platform droid       # Factory Droid
# graphify install --platform trae
# graphify install --platform cursor
# graphify install --platform gemini

# Usuários do Windows, caso haja problemas, especifique explicitamente a plataforma:
graphify install --platform windows

Após a instalação, seu assistente de codificação por IA reconhecerá o comando /graphify.

Passo 2 — Primeira execução: gerar o grafo de conhecimento

Entre em qualquer diretório de código que você queira analisar e execute:

# Analisar o diretório atual
/graphify .

# Analisar um diretório específico
/graphify ./src

# Analisar o diretório específico e ativar um modo de inferência mais agressivo
/graphify ./src --mode deep

# Pular a visualização em HTML, gerando apenas relatório e JSON (mais rápido)
/graphify ./src --no-viz

graphify segue um processo em três etapas:

1. Extração de AST (sem LLM) — usa tree-sitter para analisar arquivos de código, extraindo classes, funções, relações de importação, call graph, docstrings e comentários explicativos
2. Extração semântica (chamadas ao LLM) — para documentos, artigos, imagens etc., chama Claude para extrair conceitos, relações e motivações de design
3. Construção do grafo e clusterização — combina todas as extrações e aplica o algoritmo de detecção de comunidades Leiden (baseado na densidade das arestas, sem embeddings) para agrupar

Ao final, no diretório graphify-out/ aparecem três resultados:

ls graphify-out/
# graph.json  GRAPH_REPORT.md  graph.html  cache/

Passo 3 — Como usar os três artefatos

graphify-out/graph.json — a estrutura persistente do grafo

Esse é o núcleo do sistema. O formato é uma exportação JSON padrão do NetworkX:

{
  "nodes": [
    {
      "id": "DigestAuth",
      "label": "DigestAuth",
      "source_file": "src/auth.py",
      "source_location": "L42",
      "community": "auth"
    }
  ],
  "edges": [
    {
      "source": "DigestAuth",
      "target": "Response",
      "relation": "imports",
      "confidence": "EXTRACTED",
      "confidence_score": 1.0
    },
    {
      "source": "Attention",
      "target": "Adam",
      "relation": "semantically_similar_to",
      "confidence": "INFERRED",
      "confidence_score": 0.87
    }
  ]
}

Cada aresta tem uma tag confidence:

• EXTRACTED: relação existente diretamente no código-fonte (confiança 1.0)
• INFERRED: inferência razoável, com confidence_score (0.0–1.0)
• AMBIGUOUS: relação incerta, marcada no relatório para revisão humana

graphify-out/GRAPH_REPORT.md — relatório de análise estruturada

Esse é um resumo pensado para o assistente de IA, contendo:

• God Nodes: os conceitos centrais com maior grau (por onde todos os outros nós passam)
• Surprising Connections: conexões inesperadas entre arquivos e tipos diferentes, com explicação do “por quê”
• Suggested Questions: 4–5 perguntas que o grafo consegue responder de forma única
• Design Rationale: motivações de design extraídas das docstrings e comentários (por exemplo, # NOTE:, # WHY:, # HACK:)

graphify-out/graph.html — grafo interativo

Abra diretamente no navegador. Ele permite clicar nos nós, buscar e filtrar por comunidade. É ideal para exploração manual da estrutura do código.

Passo 4 — Consultar o grafo: três comandos principais

Ter o grafo não basta; você precisa conseguir consultá-lo. O graphify traz três comandos de consulta:

query — consulta semântica

# O mais usado: encontrar nós e caminhos relacionados à pergunta
graphify query "what connects Attention to the optimizer?"

# Limitar o orçamento de tokens
graphify query "show the auth flow" --budget 1500

# Usar DFS para rastrear o caminho específico (em vez de amostragem aleatória)
graphify query "what connects DigestAuth to Response?" --dfs

# Especificar um caminho para um grafo que não é o padrão
graphify query "..." --graph path/to/another-graph.json

A saída inclui rótulos dos nós, tipo de aresta, nível de confiança, arquivo de origem e posição no código. Você pode colar essa saída diretamente no assistente de IA para ele responder à pergunta:

Use this graph query output to answer the question. Prefer the graph
structure over guessing, and cite the source files when possible.

path — encontrar o caminho entre dois nós

# Rastrear o caminho completo do nó A até o nó B
graphify path "DigestAuth" "Response"

explain — explicar o contexto de um nó específico

# Exibir vizinhos, comunidade e arestas relacionadas a um nó
graphify explain "SwinTransformer"

Passo 5 — Integrar Always-On Hook (configuração recomendada)

Digitar manualmente /graphify toda vez ainda é meio chato. O graphify permite injetar automaticamente o conhecimento do grafo no contexto da conversa do assistente de IA, para que, ao fazer perguntas, ele priorize o grafo em vez de sair buscando cegamente nos arquivos.

Claude Code

graphify claude install

Ele faz duas coisas: escreve uma seção de regras no CLAUDE.md (para o Claude ler o GRAPH_REPORT.md) e instala um PreToolUse hook no settings.json, de modo que antes de cada chamada de Glob e Grep ele injete o prompt do grafo:

graphify: Knowledge graph exists. Read GRAPH_REPORT.md for god nodes
and community structure before searching raw files.

OpenClaw / Aider / Trae etc.

Essas plataformas não suportam tool hooks; use o AGENTS.md:

graphify claw install   # OpenClaw
graphify aider install  # Aider
graphify trae install   # Trae

Cursor

graphify cursor install

Grava em .cursor/rules/graphify.mdc e define alwaysApply: true. O Cursor carrega automaticamente em cada conversa.

Para desinstalar, use os comandos de uninstall correspondentes:

graphify claude uninstall
graphify cursor uninstall
# ...

Passo 6 — Atualização incremental: parar de reconstruir tudo sempre

Os repositórios mudam todos os dias; reconstruir tudo do zero fica lento. O graphify tem dois mecanismos de incremento:

--update: extração incremental baseada em cache SHA256

# Processar apenas arquivos que mudaram e mesclar no grafo existente
/graphify ./src --update

No diretório cache, o resultado anterior é registrado por hash do conteúdo do arquivo. O graphify compara o hash: somente os arquivos alterados passam novamente pelo fluxo de extração de AST e LLM.

--watch: monitorar automaticamente mudanças nos arquivos

# Rodar em segundo plano; ao salvar arquivos, reconstrói o AST imediatamente
/graphify ./src --watch

# Após mudanças em documentos/imagens, ele vai pedir que você rode manualmente --update

A reconstrução disparada por mudanças no código via --watch é apenas AST, portanto é bem rápida e não chama LLM. Mudanças em documentos e imagens ainda exigem reextração com LLM, então o watch notifica para você rodar manualmente uma vez o --update.

Passo 7 — Git Hooks: reconstruir o grafo a cada commit

Não quer rodar manualmente e nem abrir um processo em background? Então entregue a reconstrução do grafo ao próprio git:

graphify hook install

Isso escreve dois hooks em .git/hooks/: post-commit e post-checkout. A cada commit ou troca de branch, o git dispara a reconstrução do grafo. Se a reconstrução falhar (erro de parsing AST, timeout de LLM etc.), o hook interrompe a operação do git com um código de saída diferente de zero, evitando falhas silenciosas.

Ver status e desinstalar:

graphify hook status
graphify hook uninstall

Passo 8 — Uso avançado

MCP Server: acesso nativo do AI ao grafo

Se o seu assistente de IA suportar o protocolo MCP, exponha o grafo como uma ferramenta MCP:

python -m graphify.serve graphify-out/graph.json

A saída será uma configuração MCP stdio; basta colar essa configuração na configuração MCP do seu assistente de IA. As ferramentas expostas incluem:

• query_graph: consulta de subgrafo semântica
• get_node: obter detalhes do nó
• get_neighbors: obter nós vizinhos
• shortest_path: encontrar o menor caminho entre dois nós

Exportação para Neo4j

Quer importar o grafo para o Neo4j para fazer análises mais profissionais?

# Gerar script Cypher (importar manualmente)
/graphify ./src --neo4j

# Ou enviar diretamente para uma instância Neo4j em execução
/graphify ./src --neo4j-push bolt://localhost:7687

Gerar uma Wiki legível por agentes

# Exportar como wiki em Markdown; agentes de IA podem navegar lendo os arquivos
/graphify ./src --wiki

Gera graphify-out/wiki/index.md (entrada) + um artigo Markdown para cada comunidade e para cada god node.

Tipos de arquivo suportados

Especificar outro provedor de LLM

graphify usa por padrão o modelo embutido da sua plataforma (Claude Code usa Anthropic; Codex usa OpenAI). Se você quiser forçar o uso de outro modelo, pode especificar via variáveis de ambiente (consulte o arquivo skill.md correspondente).

Solução de problemas (FAQ)

1. Após instalar, o comando graphify não é encontrado

Geralmente é questão de ambiente Python ou PATH:

# Confirmar o local da instalação do pacote
pip show graphifyy

# Usar python -m (não depende de PATH)
python -m graphify --help

# Ou instalar isolado com pipx (recomendado)
pip install pipx && pipx install graphifyy

2. O grafo tem poucos nós ou quase nada

Verifique se o alvo não foi excluído por engano pela .graphifyignore:

# Ver quais arquivos o graphify realmente varreu
/graphify ./src --no-viz  # Execute apenas AST; não chama LLM, então é rápido

# Conferir a sintaxe do .graphifyignore (igual à do .gitignore)
cat .graphifyignore

Também pode ser que o tipo de arquivo não esteja na lista de suportados — confirme se a extensão dos seus arquivos de código está na tabela acima (“Tipos de arquivo suportados”).

3. Timeout na etapa de extração do LLM ou erro de API

Problemas de rede ou configuração incorreta da API Key:

# Confirmar se a API Key existe (usuários do Claude Code geralmente são configurados automaticamente)
# Usuários de outras plataformas verifiquem a variável de ambiente da API Key do respectivo ambiente

# Limitar tokens com --budget para evitar pedidos grandes demais
/graphify ./src --budget 2000

# Em caso de timeout, pular forçadamente e continuar com os outros arquivos (não bloqueia a execução inteira)

4. cache causando inconsistência na atualização incremental

Cache SHA256 corrompido ou arquivos modificados externamente:

# Limpar cache e forçar reconstrução total
rm -rf graphify-out/cache
/graphify ./src

# Ou limpar apenas o cache de um arquivo específico
rm graphify-out/cache/<correspondente-hash>.json
/graphify ./src --update

5. PreToolUse Hook do Claude Code não funciona

Normalmente é problema de caminho ou formato em settings.json:

# Verificar se os hooks foram escritos corretamente
cat ~/.claude/settings.json | grep graphify

# Se o IDE alterou o formato, adicione manualmente a parte do hook do graphify
# Consulte o formato do PreToolUse hook no skill.md do graphify

6. --watch reclama que watchdog está ausente

watchdog é uma dependência opcional:

pip install graphifyy[watch]

Leitura adicional / Direções avançadas

1. Extrator customizado: adicionar suporte a uma nova linguagem

Se o seu repositório usar uma linguagem que o graphify ainda não suporta (por exemplo, Racket ou Nim), é possível adicionar uma nova função extract_<lang> em extract.py. Baseie-se na extração de AST via tree-sitter e siga a seção “Adding a new language extractor” no ARCHITECTURE.md. O fluxo é bem claro: escrever a função → registrar o sufixo → adicionar dependências → criar testes.

2. Pipeline GraphRAG: conectar a consulta do grafo a um RAG

a principal vantagem do graphify é que: em cada consulta, você não precisa reler os arquivos originais — o consumo de tokens cai de O(n×tamanho do arquivo) para o tamanho do subgrafo. Ao combinar com um RAG Pipeline, a forma sugerida de integração é:

import json

# 1. Usar o GRAPH_REPORT.md para decisão de intenção em nível alto
# 2. Em seguida, usar graphify query para buscar o subgrafo relevante
# 3. Passar o subgrafo como contexto para o LLM

with open("graphify-out/graph.json") as f:
    graph = json.load(f)

# graph["nodes"] e graph["edges"] são o contexto

3. Penpax: visão de gêmeo digital local do autor do graphify

a rota de longo prazo do graphify é o Penpax — um projeto de gêmeo digital local que conecta atas de reuniões, histórico do navegador, arquivos, e-mails e código em um único grafo de conhecimento atualizado continuamente. Não sobe para a nuvem e não precisa treinar modelos com seus dados.

4. Extensão multimodal: transformar cursos em vídeo em um grafo

Se você tiver palestras técnicas, vídeos de Conferências ou áudio de podcasts, pode usar a dependência --video para incluí-los no grafo de conhecimento:

pip install 'graphifyy[video]'
/graphify ./corpus --whisper-model medium

O Whisper roda localmente; o áudio não sai da sua máquina. Os resultados da transcrição são armazenados em cache em graphify-out/transcripts/. Ao executar de novo, o processo lê o cache.

5. Colaboração do grafo: compartilhar estrutura de conhecimento em equipe

Os artefatos do graphify (como graph.json e GRAPH_REPORT.md) são texto puro, então podem ser committados no git. Depois que membros da equipe fazem pull, o graphify hook install reutiliza automaticamente a mesma versão do grafo. Isso significa que o conhecimento de arquitetura pode ter versionamento; durante code review, você pode citar nós do grafo e, nos descrições de PR, pode referenciar diretamente god nodes. Dessa forma, a compreensão do time deixa de depender de “quem pergunta a quem”.