🧰 Pré-requisitos e instalação
Este é o módulo mais "mão na massa" da trilha: você confere o Python, instala o uv, põe a CLI graphifyy no terminal, registra a skill no Claude Code e deixa o Obsidian pronto. Cada comando vem numa caixa copiar e rodar, com objetivo e como verificar.
🐍 Checar Python e instalar o uv
O Graphify é escrito em Python e pede a versão 3.10 ou mais nova. Antes de instalar qualquer coisa, confira o que você já tem com python --version. Se aparecer 3.10, 3.11, 3.12 ou superior, você está pronto. Em seguida instalamos o uv, a forma recomendada de instalar a CLI.
🔰 Novo aqui? O que é o "uv"
O uv é um instalador de pacotes e ferramentas Python — rápido e moderno, criado pela Astral. Pense nele como uma loja de aplicativos do mundo Python: você pede uma ferramenta e ele a deixa disponível como comando no terminal. É o caminho mais limpo para instalar o Graphify sem bagunçar o seu Python.
Objetivo: confirmar que o Python é 3.10+ e instalar o uv.
# 1) checar a versão do Python (precisa ser 3.10+) python --version # 2) instalar o uv (instalador oficial da Astral) curl -LsSf https://astral.sh/uv/install.sh | sh
Como verificar: o primeiro comando imprime algo como Python 3.11.x; o instalador do uv termina com uma mensagem de sucesso. Feche e reabra o terminal para o comando uv passar a responder.
🔑 Conceitos-chave
📦 Instalar a CLI graphifyy
O pacote no PyPI chama-se graphifyy — com dois "y". Ele instala o binário graphify (um "y"), que é o comando que você vai chamar. Um cuidado de digitação que evita o erro mais comum: o que você instala tem dois y; o que você roda tem um.
🔰 Novo aqui? O que é uma "CLI"
Uma CLI (Command Line Interface) é um programa que você usa por comandos de texto no terminal, em vez de cliques. PyPI é o repositório oficial de pacotes Python — a "prateleira" de onde o uv/pip baixa o graphifyy.
Objetivo: deixar o comando graphify disponível no terminal.
# recomendado (com uv) uv tool install graphifyy # alternativas, se você não usa uv pipx install graphifyy pip install graphifyy # se o comando "graphify" não for encontrado depois: uv tool update-shell
Como verificar: abrir um novo terminal e digitar graphify deve responder (a checagem completa fica no tópico 6). Se "comando não encontrado" persistir, rode uv tool update-shell e reabra o terminal.
✓ O jeito recomendado
- ✓
uv tool install graphifyyisola a ferramenta. - ✓Não mistura com o Python do sistema.
- ✓Atualizar e remover é simples depois.
✗ Erros comuns
- ✗Digitar
graphify(um y) no install. - ✗Esquecer de reabrir o terminal.
- ✗Confundir o pacote com a skill.
🔑 Conceitos-chave
🔌 Registrar a skill (graphify install)
Ter a CLI não basta: para usar o Graphify dentro do Claude Code você precisa registrar a skill. O comando graphify install escreve um arquivo SKILL.md no lugar onde o Claude Code procura suas skills — e é isso que liga o slash command /graphify.
🔰 Novo aqui? O que é uma "skill" e o SKILL.md
Uma skill é uma habilidade que você ensina ao Claude Code: um arquivo SKILL.md que descreve o que ela faz e como acioná-la. Quando esse arquivo existe em ~/.claude/skills/, o comando /graphify aparece dentro da sessão.
Objetivo: ativar o comando /graphify no Claude Code.
# registra a skill para todos os projetos (escreve ~/.claude/skills/graphify/SKILL.md) graphify install # versão por-projeto (grava .claude/skills/graphify/ no repo atual, dá pra commitar) graphify install --project
Como verificar: confirme que o arquivo existe com ls ~/.claude/skills/graphify/SKILL.md. Numa sessão nova do Claude Code, digitar /graphify deve mostrar a skill.
↑ A instalação tem dois passos distintos: instalar a CLI (tópico 2) e registrar a skill (este). O SKILL.md é a ponte que faz o /graphify existir dentro do Claude Code.
🔑 Conceitos-chave
🔮 Instalar e abrir o Obsidian
O Obsidian é onde o mapa gerado vai morar e ser navegado. Baixe-o em obsidian.md, instale e abra — é gratuito e roda no desktop (Windows, macOS, Linux). Aqui não há comando de terminal: é clicar, baixar e instalar como qualquer aplicativo. Ainda não precisa criar nada; só deixá-lo pronto para quando o markdown chegar (módulo 2.4).
🔰 Novo aqui? O que é "Obsidian" e "vault"
O Obsidian é um aplicativo de notas em markdown com links entre páginas (PKM — gestão pessoal de conhecimento). Um vault é simplesmente uma pasta de notas que ele abre — nada mais que arquivos .md numa pasta. O Graphify vai gerar exatamente esses arquivos.
✓ Faça agora
- ✓Baixar em
obsidian.mde instalar. - ✓Abrir o app ao menos uma vez.
- ✓Conferir que é a versão desktop, grátis.
○ Ainda não precisa
- ○Criar um vault (o Graphify gera depois).
- ○Instalar plugins ou pagar nada.
- ○Configurar sincronização na nuvem.
🔑 Conceitos-chave
🔑 API keys: quando precisa (e quando não)
Esta é a dúvida que mais trava gente. A regra curta: rodando via /graphify dentro do Claude Code, você não precisa de chave — a própria sessão fornece o modelo. Só o modo headless (terminal puro, sobre documentos) pede a ANTHROPIC_API_KEY. E extração de código não usa chave nenhuma — ela é feita pela AST, sem LLM.
🔰 Novo aqui? "API key", "headless" e "AST"
Uma API key é uma senha que autoriza um programa a chamar o modelo cobrando da sua conta. Headless é rodar sem interface, direto no terminal. AST (árvore sintática) é a leitura estrutural do código — o Graphify usa a biblioteca tree-sitter para isso, então código vira grafo sem chamar um LLM.
↑ Dois dos três caminhos não pedem chave. Você só precisa exportar a ANTHROPIC_API_KEY quando roda o Graphify de forma headless sobre documentos.
Objetivo: só para o caso headless — fornecer a chave ao terminal. Troque <sua-chave> pela sua.
# só no modo headless sobre documentos (NÃO precisa dentro do /graphify) export ANTHROPIC_API_KEY=<sua-chave>
Como verificar: com a variável exportada, o Graphify headless para de reclamar de chave ausente e processa os documentos. Dentro do Claude Code você pode pular este passo inteiro.
🔑 Conceitos-chave
✅ Verificar que tudo funciona
Antes de seguir para o módulo 2.2, faça o sanity check: dois comandos confirmam que a CLI responde e que a skill está registrada. Pegar um problema agora custa segundos; descobri-lo no meio de uma extração custa muito mais.
Objetivo: confirmar CLI + skill antes de extrair qualquer grafo.
# a CLI responde e lista os subcomandos? graphify --help # a skill foi registrada no lugar certo? ls ~/.claude/skills/graphify/SKILL.md
Como verificar: o primeiro comando imprime a lista de subcomandos; o segundo imprime o caminho do SKILL.md (e não "arquivo não encontrado"). Se os dois respondem, o ambiente está pronto.
✅ Checklist do ambiente
- ✓
python --versionmostra 3.10+. - ✓
graphify --helplista os subcomandos. - ✓
~/.claude/skills/graphify/SKILL.mdexiste. - ✓Obsidian instalado e aberto ao menos uma vez.
🔑 Conceitos-chave
✋ Auto-recuperação (opcional, não bloqueia): você vai rodar /graphify dentro do Claude Code. Precisa exportar a ANTHROPIC_API_KEY?
📌 Resumo do módulo
python --version e o uv instalado.uv tool install graphifyy (dois y) deixa o comando graphify no terminal.graphify install escreve o SKILL.md e liga o /graphify.obsidian.md e aberto, esperando o vault.Próximo módulo
2.2 · Escolher e preparar a fonte — decidir entre código e documentos, baixar o corpus e organizar a pasta que o Graphify vai ler.