convez.ai
SkillDesenvolvimento WebIntermediário
safishamsi

Graphify

safishamsi/graphify

Converta código e documentação em grafos de conhecimento consultáveis

Ver no GitHub
ExcelentePluginScore · de 0 a 100

Skill 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/graphify

1 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

Estrelas
150 mil
Forks
14 mil
Acompanhando
433
Saúde
57%
Último commit
há 1 dia
Versão
v0.9.112
Issues abertas
1,7 mil
Contribuidores
76

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

RequisitoMínimoVerificarInstalar
Python3.10+python --versionpython.org
uv (recomendado)qualqueruv --versioncurl -LsSf https://astral.sh/uv/install.sh | sh
pipx (alternativa)qualquerpipx --versionpip 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 pacotes graphify* no PyPI não são afiliados. O comando da CLI continua sendo graphify.

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? Use uv tool install graphifyy ou pipx install graphifyy — ambos colocam a CLI automaticamente em PATH. Com o pip simples, adicione ~/.local/bin (Linux) ou ~/Library/Python/3.x/bin (Mac) ao seu PATH, ou execute python -m graphify.

Evite usar pip install no Mac/Windows se possível. A habilidade resolve o Python em tempo de execução a partir de graphify-out/.graphify_python; se isso apontar para um ambiente diferente do onde o pacote foi instalado pelo pip, você receberá ModuleNotFoundError: No module named 'graphify'. O uv tool install e pipx install isolam o pacote em seu próprio env e evitam isso completamente.

Git hooks e uv tool / pipx: graphify hook install embute 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/bin não está em PATH. Se reinstalar ou atualizar o graphify, execute novamente graphify hook install para refrescar o caminho embutido.

Escolha sua plataforma

PlataformaComando de instalação
Claude Code (Linux/Mac)graphify install
Claude Code (Windows)graphify install (detectado automaticamente) ou graphify install --platform windows
CodeBuddygraphify install --platform codebuddy
Codexgraphify install --platform codex
OpenCodegraphify install --platform opencode
Kilo Codegraphify install --platform kilo
GitHub Copilot CLIgraphify install --platform copilot
VS Code Copilot Chatgraphify vscode install
Aidergraphify install --platform aider
OpenClawgraphify install --platform claw
Factory Droidgraphify install --platform droid
Traegraphify install --platform trae
Trae CNgraphify install --platform trae-cn
Gemini CLIgraphify install --platform gemini
Hermesgraphify install --platform hermes
Kimi Codegraphify install --platform kimi
Ampgraphify amp install
Kiro IDE/CLIgraphify kiro install
Pi coding agentgraphify install --platform pi
Cursorgraphify cursor install
Devin CLIgraphify devin install
Google Antigravitygraphify 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 $graphify em vez de /graphify.

Extras opcionais

Instale apenas o que você precisa:

ExtraO que adicionaInstalar
pdfExtração de PDFuv tool install "graphifyy[pdf]"
officeSuporte a .docx e .xlsxuv tool install "graphifyy[office]"
googleRenderização do Google Sheetsuv tool install "graphifyy[google]"
videoTranscrição de vídeo/áudio (faster-whisper + yt-dlp)uv tool install "graphifyy[video]"
mcpServador stdio do MCPuv tool install "graphifyy[mcp]"
neo4jSuporte ao push para Neo4juv tool install "graphifyy[neo4j]"
svgExportação de gráfico SVGuv tool install "graphifyy[svg]"
leidenDetecção de comunidades Leiden (apenas Python < 3.13)uv tool install "graphifyy[leiden]"
ollamaInferência local do Ollamauv tool install "graphifyy[ollama]"
openaiAPIs OpenAI / compatíveis com OpenAIuv tool install "graphifyy[openai]"
geminiAPI Google Geminiuv tool install "graphifyy[gemini]"
anthropicAPI Anthropic Claude (--backend claude, usa ANTHROPIC_API_KEY)uv tool install "graphifyy[anthropic]"
bedrockAWS Bedrock (usa IAM, sem chave de API)uv tool install "graphifyy[bedrock]"
azureAzure OpenAI Service (--backend azure, usa AZURE_OPENAI_API_KEY + AZURE_OPENAI_ENDPOINT)uv tool install "graphifyy[openai]"
sqlExtração de esquema SQLuv tool install "graphifyy[sql]"
postgresIntrospecção em tempo real do PostgreSQL (--postgres DSN)uv tool install "graphifyy[postgres]"
dmExtraçã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]"
terraformExtração AST de Terraform / HCL .tf/.tfvars/.hcluv tool install "graphifyy[terraform]"
chineseSegmentação de consultas em chinês (jieba)uv tool install "graphifyy[chinese]"
allTudo acimauv tool install "graphifyy[all]"

Faça seu assistente sempre usar o grafo

Execute isso uma vez no projeto após construir um grafo:

PlataformaComando
Claude Codegraphify claude install
CodeBuddygraphify codebuddy install
Codexgraphify codex install
OpenCodegraphify opencode install
Kilo Codegraphify kilo install
GitHub Copilot CLIgraphify copilot install
VS Code Copilot Chatgraphify vscode install
Aidergraphify aider install
OpenClawgraphify claw install
Factory Droidgraphify droid install
Traegraphify trae install
Trae CNgraphify trae-cn install
Cursorgraphify cursor install
Gemini CLIgraphify gemini install
Hermesgraphify hermes install
Kimi Codegraphify install --platform kimi
Ampgraphify amp install
Kiro IDE/CLIgraphify kiro install
Pi coding agentgraphify pi install
Devin CLIgraphify devin install
Google Antigravitygraphify 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, INFERRED ou AMBIGUOUS. Você sempre sabe o que foi encontrado vs. adivinhado.

Quais arquivos ele processa

TipoExtensõ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 / URLsqualquer 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.json agora é 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:

  1. Uma pessoa executa /graphify . e committa graphify-out/.
  2. Todos fazem pull — seu assistente lê o grafo imediatamente.
  3. Execute graphify hook install para reconstruir automaticamente após cada commit (apenas AST, sem custo de API). Isso também configura um driver de merge do git, assim graph.json nunca fica com marcadores de conflito — dois devs committando em paralelo têm seus grafos union-merged automaticamente.
  4. Quando docs ou papers mudam, execute /graphify --update para 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.

FlagPadrãoPropósito
--transport {stdio,http}stdioTransporte para servir em
--host127.0.0.1Host de vínculo HTTP (use 0.0.0.0 para expor além do localhost)
--port8080Porta de vínculo HTTP
--api-keyenv GRAPHIFY_API_KEYRequerir Authorization: Bearer <key> (ou X-API-Key)
--path/mcpCaminho montado em HTTP
--json-responseoffRetornar JSON puro ao invés de streams SSE
--statelessoffSem estado por sessão (para implantações balanceadas / CI)
--session-timeout3600Coletar 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ão python. 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ávelUsado paraQuando necessário
ANTHROPIC_API_KEYBackend Claude (Anthropic)--backend claude
GEMINI_API_KEY ou GOOGLE_API_KEYBackend Google Gemini--backend gemini
OPENAI_API_KEYAPIs OpenAI ou compatíveis com OpenAI--backend openai
DEEPSEEK_API_KEYBackend DeepSeek--backend deepseek
MOONSHOT_API_KEYBackend Kimi Code--backend kimi
OLLAMA_BASE_URLURL de inferência local do Ollama--backend ollama (padrão: http://localhost:11434)
OLLAMA_MODELNome do modelo do Ollama--backend ollama (padrão: detecção automática)
GRAPHIFY_OLLAMA_NUM_CTXSobrescrever o tamanho da janela de KV-cache do Ollamaopcional — dimensionado automaticamente por padrão
GRAPHIFY_OLLAMA_KEEP_ALIVEMinutos para manter o modelo do Ollama carregadoopcional — defina como 0 para descarregar após cada chunk
AZURE_OPENAI_API_KEYBackend Azure OpenAI Service--backend azure
AZURE_OPENAI_ENDPOINTURL de endpoint de recurso Azure--backend azure (necessário junto com a chave da API)
AZURE_OPENAI_API_VERSIONSobrescrever versão da API do Azureopcional — padrão 2024-12-01-preview
AZURE_OPENAI_DEPLOYMENT ou GRAPHIFY_AZURE_MODELNome de implantação do Azureopcional — padrão gpt-4o
AWS_* / ~/.aws/credentialsAWS Bedrock — cadeia de credenciais padrão--backend bedrock (sem chave da API, usa IAM)
GRAPHIFY_MAX_WORKERSContagem de threads para paralelismo do ASTopcional — também via flag --max-workers
GRAPHIFY_MAX_OUTPUT_TOKENSAumentar limite de saída para corpora densosopcional — ex: 32768 para arquivos grandes
GRAPHIFY_API_TIMEOUTTimeout por chamada em segundos para HTTP, claude-cli e backends do SDK Anthropic (padrão: 600)opcional — também via flag --api-timeout
GRAPHIFY_FORCEForçar reconstrução do gráfico mesmo com menos nósopcional — também via flag --force
GRAPHIFY_GOOGLE_WORKSPACEHabilitar automaticamente exportação para Google Workspaceopcional — defina como 1
GRAPHIFY_TRIAGE_BACKENDBackend para graphify prs --triageopcional — detectado automaticamente a partir das chaves disponíveis
GRAPHIFY_TRIAGE_MODELSobrescrever modelo para triagemopcional — ex: claude-opus-4-7
GRAPHIFY_QUERY_LOGSobrescrever caminho do log de consultas (padrão: ~/.cache/graphify-queries.log)opcional — defina como vazio ou /dev/null para silenciar
GRAPHIFY_QUERY_LOG_DISABLEDefina como 1 para desabilitar completamente o registro de consultasopcional
GRAPHIFY_QUERY_LOG_RESPONSESDefina como 1 também para registrar respostas completas do subgráfico (desligado por padrão)opcional
GRAPHIFY_MAX_GRAPH_BYTESSobrescrever limite de tamanho do arquivo graph.json de 512 MiB — ex: 700MB, 2GB ou bytes purosopcional — útil para corpora muito grandes
GRAPHIFY_LLM_TEMPERATURESobrescrever temperatura da LLM para extração semântica — ex: 0.7, ou none para omitiropcional — 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 extract roda 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). O graphify extract headless requer GEMINI_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ário claude CLI (Claude Code — sem chave da API, usa sua assinatura Claude). A flag --dedup-llm usa a mesma chave.
  • Residência dos dados — graphify extract detecta 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 explain e MCP query_graph é registrada em ~/.cache/graphify-queries.log no formato JSON Lines (timestamp, pergunta, corpus, nós retornados, duração). Respostas completas do subgráfico não são armazenadas por padrão. Defina GRAPHIFY_QUERY_LOG_DISABLE=1 para optar pela exclusão ou GRAPHIFY_QUERY_LOG=/dev/null para 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/bin ao seu PATH em ~/.zshrc
  • Linux: adicione ~/.local/bin ao 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-only auto-nomeia-as usando o backend configurado (integrado ou provedor OpenAI-compatível personalizado) — passe --no-label para manter Community N, ou execute graphify label para gerar nomes sob demanda.


Saiba mais


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.f90 quanto sample.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/ -q e confirme que passa.
  • Adicione um arquivo fixture em tests/fixtures/ e testes em tests/test_languages.py para 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.

Ver o original no GitHub

Bom para

Relacionados