⚙️ Graphify por dentro
O que a ferramenta faz, como ela extrai conhecimento, o que ela cospe e onde ela esbarra. Sem jargão solto: cada termo (CLI, skill, AST, tree-sitter, graph.json) é definido na hora.
⚙️ O que é o Graphify (CLI + skill)
O Graphify é a ferramenta que constrói o segundo cérebro. Ele tem duas faces que parecem a mesma coisa, mas fazem trabalhos diferentes: uma CLI (um programa que você roda no terminal — o pacote se chama graphifyy, com dois "y") e uma skill que ela instala dentro do Claude Code. Entender essa dualidade evita 90% da confusão das próximas trilhas.
🔰 Novo aqui? O que é uma "CLI"
CLI = Command Line Interface, ou "programa de linha de comando". É um programa sem janelas: você digita o nome dele no terminal e ele faz o trabalho. Aqui o programa se chama graphify (o pacote que você instala é o graphifyy).
🔰 Novo aqui? O que é uma "skill"
Uma skill é um arquivo de instruções (SKILL.md) que ensina o Claude Code a fazer uma tarefa. Depois de instalada, você a chama por um slash command — um comando que começa com "/", como /graphify. A skill é a face "de dentro do Claude Code"; a CLT pura é a face "do terminal".
Na prática você instala uma vez e ganha as duas faces. O comando de instalação coloca a CLI no sistema; um segundo comando registra a skill no Claude Code (ele escreve um SKILL.md em ~/.claude/skills/graphify/). Dentro do Claude Code você não precisa de chave de API: a própria sessão fornece o modelo.
# 1) instala a CLI (recomendado, com uv) uv tool install graphifyy # 2) registra a skill /graphify dentro do Claude Code graphify install
Feito isso, dentro do Claude Code você dispara a skill apontando uma pasta. O <isto-voce-troca> é o caminho da fonte que você quer mapear:
/graphify <./pasta-da-fonte>
↑ Uma fonte entra, o graphify processa, e tudo cai em graphify-out/. O graph.json é o centro: dele derivam o visual e o relatório (tópico 3).
🔑 Conceitos-chave
🌳 Como ele extrai (AST vs LLM)
O Graphify usa dois motores de extração, e qual deles roda depende do que você apontou. Se a fonte é código, ele lê a AST via tree-sitter — rápido, determinístico e sem chave de API. Se a fonte é documento (markdown, PDF, imagem), ele usa um LLM para entender o sentido do texto e tirar dali as entidades e relações.
🔰 Novo aqui? O que é "AST" e "tree-sitter"
AST = Abstract Syntax Tree, a "árvore de sintaxe" do código: uma representação estruturada que diz "isto é uma função", "isto é uma chamada", "isto importa aquilo". O tree-sitter é a biblioteca que lê o código e monta essa árvore — entende 12 linguagens. Como é só estrutura (não interpretação), não precisa de LLM nem de chave.
🔰 Novo aqui? Por que documento precisa de LLM
Texto em prosa não tem uma "árvore" mecânica como código. Para saber que "janela de contexto" se relaciona com "tokens", é preciso entender o que está escrito — e isso é trabalho de um LLM (o modelo de IA). Por isso a extração de documentos é chamada de semântica: ela vai pelo significado, não pela forma.
↑ Dois caminhos, um mesmo destino (o grafo). Código vai pela forma (AST, sem chave); documento vai pelo sentido (LLM). Dentro do Claude Code o modelo já vem da sessão — sem chave; só o uso headless no terminal puro pede ANTHROPIC_API_KEY.
🔑 Conceitos-chave
📂 As saídas: graph.json, graph.html, GRAPH_REPORT.md
Quando o Graphify termina, ele não devolve "uma resposta" — ele cria uma pasta chamada graphify-out/ com vários arquivos. Saber qual é qual evita o pânico de "e agora, o que eu abro?" na primeira execução. São três protagonistas e um coadjuvante.
graph.json — a fonte de verdade
O grafo completo: todas as entidades, relações e comunidades. Tudo o resto deriva dele. É o arquivo que o Obsidian e o Claude Code vão consultar.
graph.html — o visual interativo
Uma página self-contained: abre direto no navegador, sem servidor. É onde você "vê" o grafo, arrasta nós e explora as conexões com o mouse.
GRAPH_REPORT.md — a auditoria em texto
Um relatório legível: os god nodes (nós mais conectados), as pontes entre comunidades e — o ouro — uma lista de perguntas sugeridas para começar a explorar.
🔰 Novo aqui? O que é "self-contained"
Self-contained = "tudo num arquivo só". O graph.html já carrega dentro de si todo o JavaScript e os dados de que precisa, então você dá dois cliques e ele abre — não precisa instalar nada nem subir um servidor.
graphify-out/ ├── graph.json # fonte de verdade — tudo deriva daqui ├── graph.html # visual interativo (abre no navegador) ├── GRAPH_REPORT.md # auditoria: god nodes + perguntas sugeridas └── cache/ # cache por arquivo (não re-chama o LLM à toa)
O coadjuvante é a pasta cache/: ela guarda o resultado por arquivo (identificado pelo hash do conteúdo) para não pagar de novo a chamada ao LLM quando nada mudou. Por isso a segunda execução costuma ser bem mais rápida que a primeira.
🔑 Conceitos-chave
🧱 Código vs documentos
O Graphify aponta para dois tipos de fonte, e a escolha muda tudo o que vem depois. Você pode mapear um code base (um repositório de código) ou um corpus de documentos (uma coleção de PDFs, markdown, notas). Não é "melhor ou pior" — são objetivos diferentes.
🔰 Novo aqui? "code base" e "corpus"
Um code base (ou "base de código") é o conjunto de arquivos de programa de um projeto. Um corpus é uma coleção de textos tratada como um todo — aqui, a documentação que você quer transformar em mapa. No curso usamos um corpus: a documentação oficial do Claude Code.
🧩 Code base (código)
- ✓Extração por AST (tree-sitter), sem chave.
- ✓Nós como
Function,Module. - ✓Bom para entender uma arquitetura.
📄 Corpus (documentos)
- ✓Extração semântica via LLM.
- ✓Nós como
Concept(conceitos). - ✓Bom para entender um assunto/documentação.
Para mapear um repositório de código no terminal puro, o comando é a face headless da CLI. Troque o <.> pelo caminho do projeto (o ponto significa "pasta atual"):
# extrai o grafo do repositório na pasta atual graphify extract <.> # ou de uma pasta específica graphify extract <./src>
A escolha entre os dois corpora também decide o destino: código costuma render um grafo que você consulta no próprio Graphify (tema da Trilha 3); documentação é o que vale a pena levar pro Obsidian, para encaixar no contexto maior do projeto. No curso seguimos o caminho dos documentos.
🔑 Conceitos-chave
📦 O modo Obsidian e o modo wiki
O grafo bruto (graph.json) é ótimo para máquinas, mas você ainda quer navegar esse conhecimento. É aí que entram dois modos de export — e eles só existem na skill (/graphify, dentro do Claude Code), não na CLI headless. São o --obsidian e o --wiki.
--obsidian
- •Um
.mdpor nó, com wikilinks[[nome]]para os vizinhos. - •Gera um
graph.canvas: as comunidades viram grupos no Canvas do Obsidian. - •É o pulo do gato do curso: o grafo vira um vault navegável.
--wiki
- •Artigos por comunidade, em estilo Wikipédia.
- •Menos atômico que o Obsidian: agrupa conceitos relacionados num texto.
- •Bom para leitura corrida; não para o grafo de backlinks.
🔰 Novo aqui? "wikilink" e "backlink"
Um wikilink é um link no formato [[nome-da-nota]] que o Obsidian entende. Quando a nota A aponta para a B, a B ganha automaticamente um backlink ("quem me cita") — é assim que o grafo de conexões aparece sozinho no Obsidian.
O comando do modo Obsidian dentro do Claude Code aponta a fonte e diz onde gravar o vault. Troque o caminho da fonte e o --obsidian-dir pelo destino que você quiser:
# exporta um vault Obsidian (um .md por nó + canvas) /graphify <./docs> --obsidian --obsidian-dir <~/vault/graphify/claude-code> # ou: artigos por comunidade, estilo Wikipédia /graphify <./docs> --wiki
🔑 Conceitos-chave
🫙 O grafo no vácuo: a limitação que o Obsidian resolve
Aqui está a honestidade do módulo: sozinho, o grafo do Graphify vive num vácuo. Ele conhece a fundo aquele corpus que você mandou — e só ele. Não sabe das suas outras notas, dos outros projetos, do contexto maior em que esse conhecimento deveria viver. É um silo: completo por dentro, isolado por fora.
💡 A limitação, em uma frase
O graph.json guarda a procedência (de qual arquivo-fonte veio cada entidade), mas os documentos-fonte não são copiados para junto do grafo — eles ficam no projeto. O grafo aponta para fora, mas não traz o resto para dentro.
- •Completo: sabe tudo sobre o corpus que recebeu.
- •Isolado: não enxerga nada além daquele corpus.
- •Estático: não se liga sozinho ao seu fluxo de trabalho.
E é exatamente por isso que o curso não para no Graphify. Levar o grafo pro Obsidian (o modo --obsidian do tópico 5) é o que tira o conhecimento do vácuo: dentro do vault ele encaixa no contexto maior — junto das suas outras notas, ligável, integrável. O grafo deixa de ser uma ilha e vira um bairro do seu segundo cérebro.
🔰 Novo aqui? O que é "silo"
Em tecnologia, silo é informação que fica fechada num lugar só, sem conversar com o resto. O grafo isolado é um silo de conhecimento; o Obsidian é o que abre as portas desse silo e conecta com o que você já tem.
🔑 Conceitos-chave
✋ Auto-recuperação (opcional, não bloqueia): das três saídas do Graphify, qual é a fonte de verdade da qual todo o resto deriva?
📌 Resumo do módulo
graphifyy no terminal e a skill /graphify dentro do Claude Code (sem chave).graphify-out/: graph.json (verdade), graph.html (visual), GRAPH_REPORT.md (auditoria).--obsidian (1 md por nó + canvas) ou --wiki (artigos por comunidade).Próximo módulo
1.4 · Obsidian como memória — por que o vault é o lugar certo para o grafo viver e como o agente o consulta.