Graphify
safishamsi/graphify
Converta código e documentação em grafos de conhecimento consultáveis
Ver no GitHubSkill de assistente de IA que transforma pastas de código, esquemas SQL, scripts e documentação em grafos de conhecimento consultáveis. Integra código da aplicação, schema de banco de dados e infraestrutura em uma única estrutura de grafo para análise e exploração inteligente.
Instalação
npx convez-ai safishamsi/graphify1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Explorar e mapear arquitetura de código complexa
- Analisar relacionamentos entre componentes, banco de dados e infraestrutura
- Gerar insights sobre dependências e estrutura de projetos legados
- Documentação executável e interativa de sistemas
Veredito

Ferramentas sólida com tração Y Combinator para transformar código em estruturas consultáveis. Útil para grandes projetos que precisam de compreensão arquitetural profunda, mas demanda curva de aprendizado e integração com pipelines existentes.
README em português
Digite /graphify no seu assistente de codificação com IA e ele mapeia todo o seu projeto — código, documentação, PDFs, imagens, vídeos — em um grafo de conhecimento que você pode consultar, ao invés de usar grep para procurar nos arquivos.
Funciona no Claude Code, Codex, OpenCode, Kilo Code, Cursor, Gemini CLI, GitHub Copilot CLI, VS Code Copilot Chat, Aider, Amp, OpenClaw, Factory Droid, Trae, Hermes, Kimi Code, Kiro, Pi, Devin CLI e Google Antigravity.
/graphify .
É só isso. Você recebe três arquivos:
graphify-out/
├── graph.html open in any browser — click nodes, filter, search
├── GRAPH_REPORT.md the highlights: key concepts, surprising connections, suggested questions
└── graph.json the full graph — query it anytime without re-reading your files
Para uma página de arquitetura legível com diagramas de fluxo da chamada Mermaid, execute:
graphify export callflow-html
Pré-requisitos
| Requisito | Mínimo | Verificar | Instalar |
|---|---|---|---|
| Python | 3.10+ | python --version | python.org |
| uv (recomendado) | qualquer | uv --version | curl -LsSf https://astral.sh/uv/install.sh | sh |
| pipx (alternativa) | qualquer | pipx --version | pip install pipx |
Instalação rápida no macOS (Homebrew):
brew install python@3.12 uv
Instalação rápida no Windows:
winget install astral-sh.uv
Ubuntu/Debian:
sudo apt install python3.12 python3-pip pipx
# or install uv:
curl -LsSf https://astral.sh/uv/install.sh | sh
Instalação
Pacote oficial: O pacote do PyPI é
graphifyy(com dois 'y'). Outros pacotesgraphify*no PyPI não são afiliados. O comando da CLI continua sendographify.
Passo 1 — instale o pacote:
# Recommended (uv puts graphify on PATH automatically):
uv tool install graphifyy
# Alternatives:
pipx install graphifyy
pip install graphifyy # may need PATH setup — see note below
Passo 2 — registre a habilidade com seu assistente de IA:
graphify install
É só isso. Abra seu assistente de IA e digite /graphify .
Para instalar a habilidade do assistente no repositório atual em vez do perfil do usuário, adicione --project:
graphify install --project
graphify install --project --platform codex
Instalações com escopo de projeto escrevem sob o diretório atual; por exemplo .claude/skills/graphify/SKILL.md ou .agents/skills/graphify/SKILL.md (além de um sidecar references/ que a habilidade carrega sob demanda) e imprimem uma dica para git add dos arquivos que podem ser commitados. Comandos por plataforma que suportam instalações com escopo de projeto aceitam o mesmo flag, como graphify claude install --project ou graphify codex install --project.
Nota PowerShell: Use
graphify ., não/graphify .— a barra inicial é um separador de caminho no PowerShell.
graphify: command not found? Useuv tool install graphifyyoupipx install graphifyy— ambos colocam a CLI automaticamente em PATH. Com opipsimples, adicione~/.local/bin(Linux) ou~/Library/Python/3.x/bin(Mac) ao seu PATH, ou executepython -m graphify.
Evite usar
pip installno Mac/Windows se possível. A habilidade resolve o Python em tempo de execução a partir degraphify-out/.graphify_python; se isso apontar para um ambiente diferente do onde o pacote foi instalado pelopip, você receberáModuleNotFoundError: No module named 'graphify'. Ouv tool installepipx installisolam o pacote em seu próprio env e evitam isso completamente.
Git hooks e uv tool / pipx:
graphify hook installembute diretamente o caminho do interpretador atual nos scripts de hook no momento da instalação, para que o post-commit hook dispare corretamente mesmo em clientes GUI do git e runners CI onde~/.local/binnão está em PATH. Se reinstalar ou atualizar o graphify, execute novamentegraphify hook installpara refrescar o caminho embutido.
Escolha sua plataforma
| Plataforma | Comando de instalação |
|---|---|
| Claude Code (Linux/Mac) | graphify install |
| Claude Code (Windows) | graphify install (detectado automaticamente) ou graphify install --platform windows |
| CodeBuddy | graphify install --platform codebuddy |
| Codex | graphify install --platform codex |
| OpenCode | graphify install --platform opencode |
| Kilo Code | graphify install --platform kilo |
| GitHub Copilot CLI | graphify install --platform copilot |
| VS Code Copilot Chat | graphify vscode install |
| Aider | graphify install --platform aider |
| OpenClaw | graphify install --platform claw |
| Factory Droid | graphify install --platform droid |
| Trae | graphify install --platform trae |
| Trae CN | graphify install --platform trae-cn |
| Gemini CLI | graphify install --platform gemini |
| Hermes | graphify install --platform hermes |
| Kimi Code | graphify install --platform kimi |
| Amp | graphify amp install |
| Kiro IDE/CLI | graphify kiro install |
| Pi coding agent | graphify install --platform pi |
| Cursor | graphify cursor install |
| Devin CLI | graphify devin install |
| Google Antigravity | graphify antigravity install |
Usuários do Codex também precisam de multi_agent = true sob [features] em ~/.codex/config.toml para extração paralela. O CodeBuddy usa o mesmo mecanismo da ferramenta Agent e hook PreToolUse que o Claude Code. Factory Droid usa a ferramenta Task para despacho paralelo de subagentes. OpenClaw e Aider usam extração sequencial (o suporte a agentes em paralelo ainda está nos primórdios nessas plataformas). Trae usa a ferramenta Agent para despacho paralelo de subagentes e não suporta hooks PreToolUse — o AGENTS.md é o mecanismo sempre ativo.
O Codex usa
$graphifyem vez de/graphify.
Extras opcionais
Instale apenas o que você precisa:
| Extra | O que adiciona | Instalar |
|---|---|---|
pdf | Extração de PDF | uv tool install "graphifyy[pdf]" |
office | Suporte a .docx e .xlsx | uv tool install "graphifyy[office]" |
google | Renderização do Google Sheets | uv tool install "graphifyy[google]" |
video | Transcrição de vídeo/áudio (faster-whisper + yt-dlp) | uv tool install "graphifyy[video]" |
mcp | Servador stdio do MCP | uv tool install "graphifyy[mcp]" |
neo4j | Suporte ao push para Neo4j | uv tool install "graphifyy[neo4j]" |
svg | Exportação de gráfico SVG | uv tool install "graphifyy[svg]" |
leiden | Detecção de comunidades Leiden (apenas Python < 3.13) | uv tool install "graphifyy[leiden]" |
ollama | Inferência local do Ollama | uv tool install "graphifyy[ollama]" |
openai | APIs OpenAI / compatíveis com OpenAI | uv tool install "graphifyy[openai]" |
gemini | API Google Gemini | uv tool install "graphifyy[gemini]" |
anthropic | API Anthropic Claude (--backend claude, usa ANTHROPIC_API_KEY) | uv tool install "graphifyy[anthropic]" |
bedrock | AWS Bedrock (usa IAM, sem chave de API) | uv tool install "graphifyy[bedrock]" |
azure | Azure OpenAI Service (--backend azure, usa AZURE_OPENAI_API_KEY + AZURE_OPENAI_ENDPOINT) | uv tool install "graphifyy[openai]" |
sql | Extração de esquema SQL | uv tool install "graphifyy[sql]" |
postgres | Introspecção em tempo real do PostgreSQL (--postgres DSN) | uv tool install "graphifyy[postgres]" |
dm | Extração AST de arquivos .dm/.dme DreamMaker BYOND (pode exigir um compilador C + python3-dev se não houver wheel compatível com sua plataforma) | uv tool install "graphifyy[dm]" |
terraform | Extração AST de Terraform / HCL .tf/.tfvars/.hcl | uv tool install "graphifyy[terraform]" |
chinese | Segmentação de consultas em chinês (jieba) | uv tool install "graphifyy[chinese]" |
all | Tudo acima | uv tool install "graphifyy[all]" |
Faça seu assistente sempre usar o grafo
Execute isso uma vez no projeto após construir um grafo:
| Plataforma | Comando |
|---|---|
| Claude Code | graphify claude install |
| CodeBuddy | graphify codebuddy install |
| Codex | graphify codex install |
| OpenCode | graphify opencode install |
| Kilo Code | graphify kilo install |
| GitHub Copilot CLI | graphify copilot install |
| VS Code Copilot Chat | graphify vscode install |
| Aider | graphify aider install |
| OpenClaw | graphify claw install |
| Factory Droid | graphify droid install |
| Trae | graphify trae install |
| Trae CN | graphify trae-cn install |
| Cursor | graphify cursor install |
| Gemini CLI | graphify gemini install |
| Hermes | graphify hermes install |
| Kimi Code | graphify install --platform kimi |
| Amp | graphify amp install |
| Kiro IDE/CLI | graphify kiro install |
| Pi coding agent | graphify pi install |
| Devin CLI | graphify devin install |
| Google Antigravity | graphify antigravity install |
Isso escreve um pequeno arquivo de configuração que instrui seu assistente a consultar o grafo de conhecimento para perguntas sobre a base de código — preferindo consultas escopadas como graphify query "<question>" em vez de ler o relatório completo ou buscar arquivos brutos. Em plataformas que suportam hooks com carga útil (Claude Code, Gemini CLI), um hook dispara automaticamente antes das chamadas estilo busca (e, no Claude Code, antes de ler arquivos fonte individualmente via as ferramentas Read/Glob) e incentiva seu assistente a seguir o caminho do grafo. Nas outras (Codex, OpenCode, Cursor etc.), os arquivos de instrução persistentes (AGENTS.md, .cursor/rules/ etc.) fornecem a mesma orientação focada na consulta primeiro. GRAPH_REPORT.md ainda está disponível para revisão ampla da arquitetura.
CodeBuddy faz as mesmas duas coisas que o Claude Code: escreve uma seção CODEBUDDY.md informando ao CodeBuddy para ler graphify-out/GRAPH_REPORT.md antes de responder perguntas sobre a arquitetura, e instala PreToolUse hooks (.codebuddy/settings.json) que disparam antes dos comandos Bash de busca e leituras de arquivos, incentivando o uso de graphify query em vez disso.
Codex escreve para AGENTS.md e também instala um hook PreToolUse em .codex/hooks.json que dispara antes de cada chamada à ferramenta Bash — mesmo mecanismo sempre ativo do Claude Code.
Para remover o graphify de todas as plataformas ao mesmo tempo: graphify uninstall (adicione --purge para também deletar graphify-out/). Ou use o comando por plataforma (ex.: graphify claude uninstall).
Kilo Code instala a habilidade Graphify em ~/.config/kilo/skills/graphify/SKILL.md e um comando nativo /graphify em ~/.config/kilo/command/graphify.md. graphify kilo install também escreve AGENTS.md mais uma plugin nativa tool.execute.before (.kilo/plugins/graphify.js + .kilo/kilo.json ou .kilo/kilo.jsonc registration) para que o Kilo obtenha o mesmo comportamento de lembrete do grafo sempre ativo através da configuração nativa .kilo.
Cursor escreve .cursor/rules/graphify.mdc com alwaysApply: true — o Cursor inclui isso automaticamente em todas as conversas, sem necessidade de hook.
O que há no relatório
- God nodes — os conceitos mais conectados do seu projeto. Tudo flui por eles.
- Conexões surpreendentes — links entre coisas que vivem em arquivos ou módulos diferentes. Classificados pela sua inesperabilidade.
- O "porquê" — comentários inline (
# NOTE:,# WHY:,# HACK:), docstrings e justificativas de design extraídas dos docs são convertidas em nós separados vinculados ao código que explicam. - Perguntas sugeridas — 4–5 perguntas para as quais o grafo está posicionado unicamente a responder.
- Tags de confiança — cada relação inferida é marcada como
EXTRACTED,INFERREDouAMBIGUOUS. Você sempre sabe o que foi encontrado vs. adivinhado.
Quais arquivos ele processa
| Tipo | Extensões |
|---|---|
| Código (36 gramáticas tree-sitter) | .py .ts .js .jsx .tsx .mjs .go .rs .java .c .cpp .h .hpp .rb .cs .kt .scala .php .swift .lua .luau .zig .ps1 .ex .exs .m .mm .jl .vue .svelte .astro .groovy .gradle .dart .v .sv .svh .sql .f .f90 .f95 .f03 .f08 .pas .pp .dpr .dpk .lpr .inc .dfm .lfm .lpk .sh .bash .json .dm .dme .dmi .dmm .dmf .sln .slnx .csproj .fsproj .vbproj .razor .cshtml (.dm/.dme requer uv tool install graphifyy[dm]) |
| Salesforce Apex | .cls .trigger (baseado em regex; classes, interfaces, enums, métodos, triggers, arestas SOQL/DML) |
| Terraform / HCL | .tf .tfvars .hcl (requer uv tool install graphifyy[terraform]) |
| Configs MCP | .mcp.json mcp.json mcp_servers.json claude_desktop_config.json — extrai nós de servidor, referências a pacotes e requisitos de variáveis de ambiente |
| Docs | .md .mdx .qmd .html .txt .rst .yaml .yml |
| Office | .docx .xlsx (requer uv tool install graphifyy[office]) |
| Google Workspace | .gdoc .gsheet .gslides (opt-in; requer autenticação com gws e --google-workspace; Planilhas precisam de uv tool install graphifyy[google]) |
| PDFs | .pdf |
| Imagens | .png .jpg .webp .gif |
| Vídeo / Áudio | .mp4 .mov .mp3 .wav e mais (requer uv tool install graphifyy[video]) |
| YouTube / URLs | qualquer URL de vídeo (requer uv tool install graphifyy[video]) |
O código é extraído localmente sem chamadas à API (AST via tree-sitter). Tudo o resto passa pela API do modelo do seu assistente IA.
Arquivos .gdoc, .gsheet e .gslides do Google Drive para desktop são ponteiros de atalho, não conteúdo de documento. Para incluir documentos nativos do Docs, Sheets e Slides no headless extraction, instale e autentique o
gws CLI, depois execute:
uv tool install "graphifyy[google]" # needed for Google Sheets table rendering
gws auth login -s drive
graphify extract ./docs --google-workspace
Você também pode definir GRAPHIFY_GOOGLE_WORKSPACE=1. O Graphify exporta atalhos para graphify-out/converted/ como sidecars em Markdown, e então extrai esses arquivos.
Comandos comuns
/graphify . # build graph for current folder
/graphify ./docs --update # re-extract only changed files
/graphify . --cluster-only # rerun clustering without re-extracting
/graphify . --cluster-only --resolution 1.5 # more granular communities
/graphify . --cluster-only --exclude-hubs 99 # suppress utility super-hubs from god-node rankings
/graphify . --no-viz # skip the HTML, just the report + JSON
/graphify . --wiki # build a markdown wiki from the graph
graphify export callflow-html # Mermaid architecture/call-flow HTML (auto-regenerates on every git commit if hook is installed)
/graphify query "what connects auth to the database?"
/graphify path "UserService" "DatabasePool"
/graphify explain "RateLimiter"
/graphify add https://arxiv.org/abs/1706.03762 # fetch a paper and add it
/graphify add <youtube-url> # transcribe and add a video
graphify hook install # auto-rebuild on git commit
graphify merge-graphs a.json b.json # combine two graphs
graphify prs # PR dashboard: CI state, review status, worktree mapping
graphify prs 42 # deep dive on PR #42 with graph impact
graphify prs --triage # AI ranks your review queue (uses whatever backend is configured)
graphify prs --conflicts # PRs sharing graph communities — merge-order risk
Veja a referência completa de comandos abaixo.
Ignorando arquivos
Crie um .graphifyignore na raiz do seu projeto — mesma sintaxe que .gitignore, incluindo negação com !.
O .gitignore é respeitado automaticamente. Se não houver .graphifyignore em uma diretório, o graphify recorre ao .gitignore naquele diretório. Se ambos existirem, .graphifyignore tem prioridade. O escopo de subdiretórios funciona da mesma forma que no git — um arquivo de ignore afeta apenas sua própria árvore.
# .graphifyignore
node_modules/
dist/
*.generated.py
# only index src/, ignore everything else
*
!src/
!src/**
Configuração para equipe
O graphify-out/ é destinado a ser commitado ao git, assim todos na equipe começam com um mapa.
Adições recomendadas em .gitignore:
graphify-out/cost.json # local only
# graphify-out/cache/ # optional: commit for speed, skip to keep repo small
O
manifest.jsonagora é portátil — as chaves são armazenadas como caminhos relativos e reancoradas no carregamento, então commitá-lo é seguro e evita uma reconstrução completa na primeira checkout.
Fluxo de trabalho:
- Uma pessoa executa
/graphify .e committagraphify-out/. - Todos fazem pull — seu assistente lê o grafo imediatamente.
- Execute
graphify hook installpara reconstruir automaticamente após cada commit (apenas AST, sem custo de API). Isso também configura um driver de merge do git, assimgraph.jsonnunca fica com marcadores de conflito — dois devs committando em paralelo têm seus grafos union-merged automaticamente. - Quando docs ou papers mudam, execute
/graphify --updatepara atualizar esses nós.
Usando o grafo diretamente
# query the graph from the terminal
graphify query "show the auth flow"
graphify query "what connects DigestAuth to Response?" --graph graphify-out/graph.json
# expose the graph as an MCP server (for repeated tool-call access)
python -m graphify.serve graphify-out/graph.json
# register with Kimi Code:
kimi mcp add --transport stdio graphify -- python -m graphify.serve graphify-out/graph.json
# or serve over HTTP so a whole team points at one URL (no local graphify needed):
python -m graphify.serve graphify-out/graph.json --transport http --port 8080
python -m graphify.serve graphify-out/graph.json --transport http --host 0.0.0.0 --api-key "$SECRET"
O servidor MCP dá ao seu assistente acesso estruturado: query_graph, get_node, get_neighbors, shortest_path, list_prs, get_pr_impact, triage_prs.
Servidor HTTP compartilhado
--transport stdio (o padrão) inicia um servidor local por desenvolvedor. --transport http serve as mesmas ferramentas sobre o transporte MCP Streamable HTTP, assim um único processo compartilhado pode servir o grafo para toda a equipe — os clientes apontam sua configuração de IDE MCP em http://<host>:8080/mcp ao invés de rodar graphify localmente.
| Flag | Padrão | Propósito |
|---|---|---|
--transport {stdio,http} | stdio | Transporte para servir em |
--host | 127.0.0.1 | Host de vínculo HTTP (use 0.0.0.0 para expor além do localhost) |
--port | 8080 | Porta de vínculo HTTP |
--api-key | env GRAPHIFY_API_KEY | Requerir Authorization: Bearer <key> (ou X-API-Key) |
--path | /mcp | Caminho montado em HTTP |
--json-response | off | Retornar JSON puro ao invés de streams SSE |
--stateless | off | Sem estado por sessão (para implantações balanceadas / CI) |
--session-timeout | 3600 | Coletar sessões stateful inativas após N segundos (0 desativa) |
O vínculo padrão em 127.0.0.1 é apenas loopback. Defina --host 0.0.0.0 e --api-key juntos ao expor em um host compartilhado. Execute-o em um container:
docker build -t graphify .
docker run -p 8080:8080 -v "$(pwd)/graphify-out:/data" graphify \
/data/graph.json --transport http --host 0.0.0.0 --api-key "$SECRET"
Nota WSL / Linux: O Ubuntu fornece
python3, nãopython. Use uma venv para evitar conflitos:python3 -m venv .venv && .venv/bin/pip install "graphifyy[mcp]"
Variáveis de ambiente
Estas são necessárias apenas para a extração headless / CI (graphify extract). Ao executar via o skill /graphify dentro do seu IDE, a API do modelo é fornecida pela sessão do seu IDE — não há necessidade de chaves extras.
| Variável | Usado para | Quando necessário |
|---|---|---|
ANTHROPIC_API_KEY | Backend Claude (Anthropic) | --backend claude |
GEMINI_API_KEY ou GOOGLE_API_KEY | Backend Google Gemini | --backend gemini |
OPENAI_API_KEY | APIs OpenAI ou compatíveis com OpenAI | --backend openai |
DEEPSEEK_API_KEY | Backend DeepSeek | --backend deepseek |
MOONSHOT_API_KEY | Backend Kimi Code | --backend kimi |
OLLAMA_BASE_URL | URL de inferência local do Ollama | --backend ollama (padrão: http://localhost:11434) |
OLLAMA_MODEL | Nome do modelo do Ollama | --backend ollama (padrão: detecção automática) |
GRAPHIFY_OLLAMA_NUM_CTX | Sobrescrever o tamanho da janela de KV-cache do Ollama | opcional — dimensionado automaticamente por padrão |
GRAPHIFY_OLLAMA_KEEP_ALIVE | Minutos para manter o modelo do Ollama carregado | opcional — defina como 0 para descarregar após cada chunk |
AZURE_OPENAI_API_KEY | Backend Azure OpenAI Service | --backend azure |
AZURE_OPENAI_ENDPOINT | URL de endpoint de recurso Azure | --backend azure (necessário junto com a chave da API) |
AZURE_OPENAI_API_VERSION | Sobrescrever versão da API do Azure | opcional — padrão 2024-12-01-preview |
AZURE_OPENAI_DEPLOYMENT ou GRAPHIFY_AZURE_MODEL | Nome de implantação do Azure | opcional — padrão gpt-4o |
AWS_* / ~/.aws/credentials | AWS Bedrock — cadeia de credenciais padrão | --backend bedrock (sem chave da API, usa IAM) |
GRAPHIFY_MAX_WORKERS | Contagem de threads para paralelismo do AST | opcional — também via flag --max-workers |
GRAPHIFY_MAX_OUTPUT_TOKENS | Aumentar limite de saída para corpora densos | opcional — ex: 32768 para arquivos grandes |
GRAPHIFY_API_TIMEOUT | Timeout por chamada em segundos para HTTP, claude-cli e backends do SDK Anthropic (padrão: 600) | opcional — também via flag --api-timeout |
GRAPHIFY_FORCE | Forçar reconstrução do gráfico mesmo com menos nós | opcional — também via flag --force |
GRAPHIFY_GOOGLE_WORKSPACE | Habilitar automaticamente exportação para Google Workspace | opcional — defina como 1 |
GRAPHIFY_TRIAGE_BACKEND | Backend para graphify prs --triage | opcional — detectado automaticamente a partir das chaves disponíveis |
GRAPHIFY_TRIAGE_MODEL | Sobrescrever modelo para triagem | opcional — ex: claude-opus-4-7 |
GRAPHIFY_QUERY_LOG | Sobrescrever caminho do log de consultas (padrão: ~/.cache/graphify-queries.log) | opcional — defina como vazio ou /dev/null para silenciar |
GRAPHIFY_QUERY_LOG_DISABLE | Defina como 1 para desabilitar completamente o registro de consultas | opcional |
GRAPHIFY_QUERY_LOG_RESPONSES | Defina como 1 também para registrar respostas completas do subgráfico (desligado por padrão) | opcional |
GRAPHIFY_MAX_GRAPH_BYTES | Sobrescrever limite de tamanho do arquivo graph.json de 512 MiB — ex: 700MB, 2GB ou bytes puros | opcional — útil para corpora muito grandes |
GRAPHIFY_LLM_TEMPERATURE | Sobrescrever temperatura da LLM para extração semântica — ex: 0.7, ou none para omitir | opcional — omitido automaticamente para modelos de raciocínio o1/o3/o4/gpt-5 |
Privacidade
- Arquivos de código — processados localmente via tree-sitter. Nada sai da sua máquina. Um corpus apenas com código não requer chave da API —
graphify extractroda totalmente offline. - Vídeo / áudio — transcritos localmente com faster-whisper. Nada sai da sua máquina.
- Docs, PDFs, imagens — enviados ao seu assistente de IA para extração semântica (via o skill
/graphify, usando qualquer modelo que a sessão do seu IDE execute). Ographify extractheadless requerGEMINI_API_KEY/GOOGLE_API_KEY(Gemini),MOONSHOT_API_KEY(Kimi),ANTHROPIC_API_KEY(Claude),OPENAI_API_KEY(OpenAI),DEEPSEEK_API_KEY(DeepSeek), uma instância do Ollama em execução (OLLAMA_BASE_URL), credenciais AWS via a cadeia de provedores padrão (Bedrock — sem chave da API, usa IAM) ou o binárioclaudeCLI (Claude Code — sem chave da API, usa sua assinatura Claude). A flag--dedup-llmusa a mesma chave. - Residência dos dados —
graphify extractdetecta automaticamente qual provedor usar com base em qual chave de API está definida (prioridade: Gemini → Kimi → Claude → OpenAI → DeepSeek → Azure → Bedrock → Ollama). Para código com requisitos de residência de dados, use--backend ollama(totalmente local) ou passe uma flag explícita--backend. A Kimi (MOONSHOT_API_KEY) roteia para servidores da Moonshot AI na China. - Sem telemetria, sem rastreamento de uso, sem análises.
- Registro de consultas — cada chamada de
graphify query,graphify path,graphify explaine MCPquery_graphé registrada em~/.cache/graphify-queries.logno formato JSON Lines (timestamp, pergunta, corpus, nós retornados, duração). Respostas completas do subgráfico não são armazenadas por padrão. DefinaGRAPHIFY_QUERY_LOG_DISABLE=1para optar pela exclusão ouGRAPHIFY_QUERY_LOG=/dev/nullpara silenciar sem desabilitar o caminho de código.
Solução de problemas
graphify: command not found após pip install graphifyy
O pip instala scripts em um diretório bin do usuário que pode não estar no seu PATH. Correção:
- macOS: adicione
~/Library/Python/3.x/binao seu PATH em~/.zshrc - Linux: adicione
~/.local/binao seu PATH em~/.bashrc - Ou use
uv tool install graphifyy/pipx install graphifyy— ambos gerenciam o PATH automaticamente.
python -m graphify funciona, mas o comando graphify não
O PATH do shell não inclui a pasta de scripts Python. Use uv ou pipx em vez do pip simples.
/graphify . causa "path not recognized" no PowerShell
O PowerShell trata uma barra / inicial como separador de caminho. No Windows, use graphify . (sem barra).
Grafo tem menos nós após --update ou rebuild
Se um refatoração apagou arquivos, os antigos nós permanecem. Passe --force (ou defina GRAPHIFY_FORCE=1) para sobrescrever mesmo quando o rebuild tiver menos nós.
Grafo tem nós duplicados para a mesma entidade (duplicatas fantasma) Duplicatas fantasma (o mesmo símbolo aparecendo duas vezes — uma vez da extração AST com localização de fonte, outra da extração semântica sem) agora são automaticamente mescladas no momento do build. Se você vir isso em um grafo construído antes da v0.8.33, execute uma re-extração completa para limpar:
graphify extract . --force
Ollama esgota VRAM / janela de contexto excedida A janela KV-cache é dimensionada automaticamente, mas pode ser muito grande para sua GPU. Reduza-a:
GRAPHIFY_OLLAMA_NUM_CTX=8192 graphify extract ./docs --backend ollama --token-budget 4000
HTML do grafo é muito grande para abrir em um navegador (>5000 nós) Pule a geração de HTML e use o JSON diretamente:
graphify cluster-only ./my-project --no-viz
graphify query "..."
graph.json tem marcadores de conflito após dois devs commitarem ao mesmo tempo
Execute graphify hook install — ele configura um driver de merge do git que mescla automaticamente graph.json, evitando conflitos.
Extração retorna nós/arestas vazios para docs ou PDFs Docs, PDFs e imagens exigem uma chamada a LLM — corpora apenas com código não precisam de chave. Verifique se sua API key está definida e o backend correto:
ANTHROPIC_API_KEY=sk-... graphify extract ./docs --backend claude
Aviso de versão incompatível da Skill no seu IDE Sua versão instalada do graphify é diferente do arquivo skill. Atualize:
uv tool upgrade graphifyy
graphify install # overwrites the skill file
Referência completa de comandos
/graphify # run on current directory
/graphify ./raw # run on a specific folder
/graphify ./raw --mode deep # more aggressive relationship extraction
/graphify ./raw --update # re-extract only changed files
/graphify ./raw --directed # preserve edge direction
/graphify ./raw --cluster-only # rerun clustering on existing graph
/graphify ./raw --no-viz # skip HTML visualization
/graphify ./raw --obsidian # generate Obsidian vault
/graphify ./raw --wiki # build agent-crawlable markdown wiki
/graphify ./raw --svg # export graph.svg
/graphify ./raw --graphml # export for Gephi / yEd
/graphify ./raw --neo4j # generate cypher.txt for Neo4j
/graphify ./raw --neo4j-push bolt://localhost:7687
/graphify ./raw --watch # auto-sync as files change
/graphify ./raw --mcp # start MCP stdio server
/graphify add https://arxiv.org/abs/1706.03762
/graphify add <video-url>
/graphify add https://... --author "Name" --contributor "Name"
/graphify query "what connects attention to the optimizer?"
/graphify query "..." --dfs --budget 1500
/graphify path "DigestAuth" "Response"
/graphify explain "SwinTransformer"
graphify uninstall # remove from all platforms in one shot
graphify uninstall --purge # also delete graphify-out/
graphify uninstall --project --platform codex # remove project-scoped install files only
graphify hook install # post-commit + post-checkout hooks
graphify hook uninstall
graphify hook status
# always-on assistant instructions - platform-specific
graphify claude install # CLAUDE.md + PreToolUse hook (Claude Code)
graphify claude uninstall
graphify codebuddy install # CODEBUDDY.md + PreToolUse hook (CodeBuddy)
graphify codebuddy uninstall
graphify codex install # AGENTS.md + PreToolUse hook in .codex/hooks.json (Codex)
graphify opencode install # AGENTS.md + tool.execute.before plugin (OpenCode)
graphify kilo install # native Kilo skill + /graphify command + AGENTS.md + .kilo plugin
graphify kilo uninstall
graphify cursor install # .cursor/rules/graphify.mdc (Cursor)
graphify cursor uninstall
graphify gemini install # GEMINI.md + BeforeTool hook (Gemini CLI)
graphify gemini uninstall
graphify copilot install # skill file (GitHub Copilot CLI)
graphify copilot uninstall
graphify aider install # AGENTS.md (Aider)
graphify aider uninstall
graphify claw install # AGENTS.md (OpenClaw)
graphify claw uninstall
graphify droid install # AGENTS.md (Factory Droid)
graphify droid uninstall
graphify trae install # AGENTS.md (Trae)
graphify trae uninstall
graphify trae-cn install # AGENTS.md (Trae CN)
graphify trae-cn uninstall
graphify hermes install # AGENTS.md + ~/.hermes/skills/ (Hermes)
graphify hermes uninstall
graphify amp install # skill file (Amp)
graphify amp uninstall
graphify kiro install # .kiro/skills/ + .kiro/steering/graphify.md (Kiro IDE/CLI)
graphify kiro uninstall
graphify pi install # skill file (Pi coding agent)
graphify pi uninstall
graphify devin install # skill file + .windsurf/rules/graphify.md (Devin CLI)
graphify devin uninstall
graphify antigravity install # .agents/rules + .agents/workflows (Google Antigravity)
graphify antigravity uninstall
graphify extract ./docs # headless LLM extraction for CI (no IDE needed)
graphify extract ./docs --backend gemini # explicit backend: gemini, kimi, claude, openai, deepseek, ollama, bedrock, or claude-cli
graphify extract ./docs --backend gemini --model gemini-3.1-pro-preview
graphify extract ./docs --backend ollama # local Ollama (set OLLAMA_BASE_URL / OLLAMA_MODEL) - no API key needed for loopback
GRAPHIFY_OLLAMA_NUM_CTX=32768 graphify extract ./docs --backend ollama # override KV-cache window (auto-sized by default)
GRAPHIFY_OLLAMA_KEEP_ALIVE=0 graphify extract ./docs --backend ollama # unload model after each chunk (saves VRAM on small GPUs)
graphify extract ./docs --backend bedrock # AWS Bedrock via IAM - no API key, uses AWS credential chain
graphify extract ./docs --backend claude-cli # route through Claude Code CLI - no API key, uses your Claude subscription
graphify extract ./docs --backend azure # Azure OpenAI (set AZURE_OPENAI_API_KEY + AZURE_OPENAI_ENDPOINT)
graphify extract ./docs --max-workers 16 # AST parallelism (also GRAPHIFY_MAX_WORKERS)
graphify extract --postgres "postgresql://user:pass@host/db" # introspect live PostgreSQL schema directly
graphify extract ./my-workspace --cargo # introspect Rust Cargo workspace dependencies directly
graphify extract ./docs --token-budget 30000 # smaller semantic chunks for local/small models
graphify extract ./docs --max-concurrency 2 # fewer parallel LLM calls (useful for local inference)
graphify extract ./docs --api-timeout 900 # longer HTTP timeout for slow local models (default 600s)
graphify extract ./docs --google-workspace # export .gdoc/.gsheet/.gslides via gws before extraction
graphify extract ./docs --mode deep # richer semantic extraction via extended system prompt
graphify extract ./docs --no-cluster # raw extraction only, skip clustering
graphify extract ./docs --force # overwrite graph.json even if new graph has fewer nodes (use after refactors or to clear ghost duplicates)
graphify extract ./docs --dedup-llm # LLM tiebreaker for ambiguous entity pairs (uses same API key)
graphify extract ./docs --global --as myrepo # extract and register into the cross-project global graph
GRAPHIFY_MAX_OUTPUT_TOKENS=32768 graphify extract ./docs --backend claude # raise output cap for dense corpora
graphify export callflow-html # graphify-out/<project>-callflow.html
graphify export callflow-html --max-sections 8 # cap generated architecture sections
graphify export callflow-html --output docs/arch.html
graphify export callflow-html ./some-repo/graphify-out
graphify global add graphify-out/graph.json myrepo # register a project graph into ~/.graphify/global.json
graphify global remove myrepo # remove a project from the global graph
graphify global list # show all registered repos + node/edge counts
graphify global path # print path to the global graph file
graphify prs # PR dashboard: CI, review, worktree, graph impact
graphify prs 42 # deep dive on PR #42
graphify prs --triage # AI triage ranking (auto-detects backend from env)
graphify prs --worktrees # worktree → branch → PR mapping
graphify prs --conflicts # PRs sharing graph communities (merge-order risk)
graphify prs --base main # filter to PRs targeting a specific base branch
graphify prs --repo owner/repo # run against a different GitHub repo
GRAPHIFY_TRIAGE_BACKEND=kimi graphify prs --triage # use a specific backend for triage
graphify clone https://github.com/karpathy/nanoGPT
graphify merge-graphs a.json b.json --out merged.json
graphify --version # print installed version
graphify watch ./src
graphify check-update ./src
graphify update ./src
graphify update ./src --no-cluster # skip reclustering, write raw AST graph only
graphify update ./src --force # overwrite even if new graph has fewer nodes
graphify cluster-only ./my-project
graphify cluster-only ./my-project --graph path/to/graph.json # custom graph location
graphify cluster-only ./my-project --resolution 1.5 # more, smaller communities
graphify cluster-only ./my-project --exclude-hubs 99 # exclude p99 degree nodes from partitioning
graphify cluster-only ./my-project --no-label # keep "Community N" placeholders
graphify cluster-only ./my-project --backend=gemini # backend for community naming
graphify label ./my-project # (re)name communities with the configured backend
graphify label ./my-project --backend=openai # force a specific backend
Nomes comunitários: dentro de um agente (Claude Code, Gemini CLI) o próprio agente nomeia as comunidades. Quando você executa a CLI básica,
cluster-onlyauto-nomeia-as usando o backend configurado (integrado ou provedor OpenAI-compatível personalizado) — passe--no-labelpara manterCommunity N, ou executegraphify labelpara gerar nomes sob demanda.
Saiba mais
- Como funciona — pipeline de extração, detecção comunitária, pontuação de confiança e benchmarks
- ARCHITECTURE.md — quebra por módulo, como adicionar uma linguagem
- Integrações opcionais — Docker MCP Toolkit + SQLite
Construído com graphify — Penpax
Penpax é a camada sempre ativa construída sobre o graphify — ela aplica a mesma abordagem de grafo à sua vida profissional inteira: reuniões, histórico do navegador, e-mails, arquivos e código, atualizando continuamente em segundo plano.
Construído para pessoas cuja vida profissional se espalha por centenas de conversas e documentos que nunca podem ser totalmente reconstruídos. Sem nuvem, tudo no dispositivo.
Teste grátis lançando em breve. Junte-se à lista de espera →
Configuração para desenvolvimento
O projeto usa uv para o fluxo de trabalho de dev. Instale uma vez, depois:
git clone https://github.com/safishamsi/graphify.git
cd graphify
git checkout v8 # active development branch
# Create the project venv and install graphify + all extras + the dev group
# (pytest). uv installs the dev dependency group by default; pass --no-dev to
# skip it.
uv sync --all-extras
Verifique a instalação editável:
uv run graphify --version
uv run python -c "import graphify; print(graphify.__file__)"
Executando testes
uv run pytest tests/ -q # run the full suite
uv run pytest tests/test_extract.py -q # one module
uv run pytest tests/ -q -k "python" # filter by name
Nota macOS: o suite de testes inclui tanto
sample.f90quantosample.F90. Eles colidem em sistemas de arquivos HFS+ / APFS insensíveis a maiúsculas/minúsculas. Execute no Linux ou em um container Docker se precisar testar ambas as variantes Fortran simultaneamente.
Fluxo de trabalho Git
- Desenvolvimento ativo acontece na branch
v8. - Estilo de commit:
fix: <descrição>/feat: <descrição>/docs: <descrição> - Antes de abrir um PR, execute
uv run pytest tests/ -qe confirme que passa. - Adicione um arquivo fixture em
tests/fixtures/e testes emtests/test_languages.pypara qualquer novo extractor de linguagem.
O que contribuir
Exemplos práticos são a contribuição mais útil. Execute /graphify em um corpus real, salve o output em worked/{slug}/, escreva uma honesta review.md cobrindo o que o grafo acertou e errou, e abra um PR.
Bugs de extração — abra um issue com o arquivo de entrada, a entrada do cache (graphify-out/cache/) e o que foi perdido ou errado.
Veja ARCHITECTURE.md para responsabilidades dos módulos e como adicionar uma linguagem.