graph.html: como explorar o grafo do seu projeto no navegador

Fala aí, beleza? Entender um projeto grande lendo arquivo por arquivo é o caminho mais lento que existe

Dá pra ver o negócio inteiro de uma vez, com os módulos, os clusters e quem conversa com quem, tudo numa tela só

É isso que o graph.html faz: ele é a saída visual do Graphify, gerada dentro da pasta graphify-out/ junto com o GRAPH_REPORT.md (o relatório de arquitetura) e o graph.json (o grafo legível por máquina)

Neste post tu vai ver como chegar até esse arquivo, clicar nos nós, buscar conceitos, filtrar por comunidade e, principalmente, quando essa visão no navegador ajuda MAIS que rodar uma consulta por comando

Bora?

O que você precisa antes de abrir o grafo

Antes do grafo existir, alguém tem que gerar ele, né? E pra isso o Graphify precisa estar instalado na máquina

A instalação recomendada é pelo pacote PyPI graphifyy, com uv, pipx ou pip:

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 114 aulas
• 4 projetos
• 9h 18min

Conhecer formação

uv tool install graphifyy
# alternativas
pipx install graphifyy
pip install graphifyy

Se liga nisso: o pacote se chama graphifyy (com dois "y" no fim), mas o comando que fica disponível no terminal é graphify

Depois de instalar o pacote, tem um segundo passo que registra a skill nos assistentes de IA detectados na máquina:

graphify install

Esse comando copia a skill /graphify pra configuração dos assistentes encontrados. E ela não é exclusiva de um só: a descrição oficial do repositório cita Claude Code, Cursor, Codex e Gemini CLI

Em instalação com escopo de projeto, a skill é escrita dentro do diretório atual, em .claude/skills/graphify/SKILL.md (ou .agents/skills/graphify/SKILL.md), com uma pasta references/ que é carregada sob demanda

E o que ele consegue mapear?

O Graphify monta um grafo único cobrindo 36 linguagens de código, além de Markdown, PDFs, documentos Office, schemas SQL, PostgreSQL ao vivo e Terraform

Ou seja: não é só o código, o "redor" do projeto entra junto

Passo a passo: do comando ao grafo aberto no navegador

1. Mapeie o projeto rodando a skill dentro do assistente

/graphify .

Esse passo é o que mapeia o projeto para graphify-out/

O erro comum aqui: tentar consultar o grafo antes de gerar ele. Todos os comandos da CLI leem o graph.json produzido nesse passo, então sem ele não existe nada pra consultar

2. Confira as três saídas em graphify-out/

ls graphify-out/
# graph.html      -> visualização interativa
# GRAPH_REPORT.md -> relatório de arquitetura
# graph.json      -> grafo legível por máquina

Cada um serve a um público diferente: o .html é pra você olhar, o .md é pra ler, o .json é pra máquina consumir

3. Abra o graphify-out/graph.html no navegador

A função to_html do Graphify gera um HTML standalone, com busca, filtro e interação já embutidos, renderizado com a biblioteca vis.js

4. Clique num nó pra ver as conexões e o painel lateral

Ao selecionar um nó, a sidebar de metadados é populada com source_file, file_type e estatísticas de degree (o grau do nó, ou seja, o tamanho da vizinhança dele)

É aqui que o grafo deixa de ser desenho bonito e vira informação: um nó com grau alto é um ponto de concentração do seu projeto, e mexer nele tende a respingar em muita coisa

5. Use a barra de busca e navegue com zoom e pan

A busca é em tempo real e filtra os nós por label, então dá pra digitar um pedaço do nome e ver a nuvem se afunilar na sua frente

Com zoom e pan tu circula pela região que sobrou

6. Filtre por comunidade pela legenda clicável

O graph.html traz uma legenda de comunidades clicável, que escurece (dim) ou destaca (highlight) clusters específicos, com as cores da paleta COMMUNITY_COLORS

Esse é o filtro mais subestimado: em vez de olhar 40 arquivos, tu isola um cluster e olha só o bairro que interessa

7. Entenda a física antes de achar que travou

A engine de física usa o solver forceAtlas2Based e é desativada automaticamente depois que o grafo estabiliza

O erro comum deste passo: ver os nós se mexendo sozinhos e achar que deu ruim. Não deu, o layout ainda está se acomodando, deixa ele terminar

8. Projeto grande? Tem teto de nós

A visualização tem um limite de 5.000 nós, definido pela constante MAX_NODES_FOR_VIZ, justamente pra não fritar o navegador

Esse limite é sobrescrevível pela variável de ambiente GRAPHIFY_VIZ_NODE_LIMIT:

export GRAPHIFY_VIZ_NODE_LIMIT=8000

Tome cuidado ao subir muito esse número: o teto existe por um motivo, e não é frescura

9. Mantenha o grafo atualizado

Código muda todo dia, e grafo velho mente

graphify query "onde o login é validado" --update

A flag --update faz um re-scan incremental, ou seja, revisita só o que mudou desde a última execução em vez de reconstruir tudo do zero

E quando a pergunta for cabeluda, existe o --mode deep, que faz uma análise multi-passo mais profunda

Quando o navegador ajuda mais que a consulta por comando

Agora a parte que quase ninguém fala: o graph.html e a CLI leem O MESMO grafo, mas não servem pra mesma coisa

O navegador ganha na exploração aberta, aquela em que você ainda não sabe direito o que está procurando

Entender a topologia geral, achar clusters, ver o que orbita um módulo específico, mostrar a arquitetura pra outra pessoa numa call sem precisar abrir 15 arquivos… é o cenário dele

A CLI ganha na pergunta fechada, quando você quer uma resposta que dê pra colar num PR:

graphify query "como o upload de arquivo chega no storage"
graphify query "como o upload de arquivo chega no storage" --dfs
graphify path "UploadController" "S3Client"
graphify explain "UploadController"

O query faz BFS por padrão, com --dfs opcional, o path devolve o caminho mais curto entre dois nós e o explain abre um nó específico

E o detalhe que faz diferença: as respostas trazem caminhos explícitos com citação file:line, e cada aresta vem rotulada como EXTRACTED, INFERRED ou AMBIGUOUS

Saber que uma ligação foi INFERIDA e não extraída muda completamente o quanto você confia nela, beleza?

Por padrão, os comandos da CLI leem o graphify-out/graph.json, e a flag --graph <caminho> aponta pra outro graph.json quando você tiver mais de um por perto

Tudo isso roda localmente, o que já resolve boa parte da desconfiança de mandar código pra fora

Tem ainda um terceiro caminho: o Graphify expõe um servidor MCP com 10 ferramentas sobre o mesmo grafo, entre elas query_graph, get_node, get_neighbors e shortest_path

O registro manual vai no .mcp.json do projeto, em mcpServers:

{
  "mcpServers": {
    "graphify": {
      "command": "python",
      "args": ["-m", "graphify.serve", "graphify-out/graph.json"]
    }
  }
}

Com isso o assistente passa a consultar o grafo sozinho, e você para de repetir a estrutura do projeto em toda conversa nova (na mesma linha de raciocínio de organizar conversas no Claude Desktop, que evita o mesmo retrabalho)

E se a tua ideia for levar esse grafo pra dentro de uma ferramenta tua, aí entra outra decisão de arquitetura, tipo escolher entre API da Anthropic ou Agent SDK pra montar o wrapper

Próximo passo: gere o grafo do seu projeto hoje

O fluxo mínimo é curtinho, se liga

Instala o pacote graphifyy, roda graphify install pra registrar a skill, chama /graphify . dentro do assistente e abre o graphify-out/graph.html

Depois disso, o combo que rende mais é usar o navegador pra ESCOLHER o alvo (aquele cluster estranho, aquele nó com grau alto demais) e a CLI pra pegar a resposta citada com file:line

Um explora, o outro comprova

O repositório oficial hoje fica em Graphify-Labs/graphify, organização fundada por Safi Shamsi, e as URLs antigas em safishamsi/graphify apontam pro mesmo projeto

E, de novo, tudo roda localmente, o que deixa o teste bem barato de fazer

Agora é contigo: gera o grafo do teu projeto e vai clicando 😀

até o próximo post!