README.pt BR

Reduza o gasto de tokens dos agentes em 80%. O Graphify Cloud é uma memória sempre ativa que governa seus agentes, mantém a qualidade do código alta e prova a correção com verificação formal. Comece um teste gratuito de 14 dias →

Digite /graphify no seu assistente de programação com IA e ele mapeia o seu projeto inteiro (código, documentos, PDFs, imagens, vídeos) em um grafo de conhecimento que você pode consultar em vez de fazer grep nos arquivos.

• Mapeamento de código grátis, totalmente local. O código é analisado com AST do tree-sitter: determinístico, sem LLM, nada sai da sua máquina. (Documentos, PDFs, imagens e vídeo usam o modelo do seu assistente, ou uma chave de API configurada, para uma passagem semântica.)
• Toda aresta é explicada. Cada conexão é marcada como EXTRACTED (explícita na fonte) ou INFERRED (resolvida pelo graphify), para que você possa distinguir o que foi lido diretamente do que foi inferido.
• Não é um índice vetorial. Sem embeddings, sem armazenamento de vetores: um grafo real que você percorre. Faça uma pergunta, trace o caminho entre duas coisas ou explique um conceito.

[!NOTE] Quer isso sempre ativo? O Graphify Cloud mantém o grafo ativo em todo o seu SDLC: suporte a monorepo e multi-repositório, verificação formal e revisão de código com uma visão panorâmica do seu SDLC, além de conectores para Sentry, Jira e mais, para que incidentes e tickets fiquem no mesmo grafo que o seu código. Comece um teste gratuito de 14 dias em app.graphify.com.

A base de código do FastAPI mapeada pelo graphify. Cada nó é um conceito, as cores são comunidades detectadas, e tudo é clicável em graph.html.

Comece agora (30 segundos). Precisa de Python 3.10+ e uv (ou pipx):

uv tool install graphifyy      # install the CLI (or: pipx install graphifyy)
graphify install               # detects your assistant and registers the skill

Depois, no seu assistente de IA:

/graphify .

Pronto. 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

O grafo persistido inclui graph.schema_version para que integrações possam detectar mudanças de formato incompatíveis, além de graph.graphify_version identificando a versão do Graphify que o produziu.

Uma instalação, qualquer assistente, qualquer SO. Claude Code, Cursor, Codex, Gemini CLI, GitHub Copilot e mais de 20 outros, no macOS, Linux e Windows: escolha sua plataforma.

Veja em ação¶

Depois que o grafo é construído, você o consulta em vez de ler arquivos. Saída real, graphify executado na base de código do FastAPI mostrada acima:

$ graphify explain "APIRouter"
Node: APIRouter
  Source:    routing.py L2210
  Community: 2
  Degree:    47

Connections (47):
  --> RequestValidationError [uses] [INFERRED]
  --> Dependant [uses] [INFERRED]
  --> .get() [method] [EXTRACTED]
  <-- __init__.py [imports] [EXTRACTED]
  ...

$ graphify path "FastAPI" "ModelField"
Shortest path (3 hops):
  FastAPI --uses--> DefaultPlaceholder <--references-- get_request_handler() --references--> ModelField

Toda aresta carrega uma marca de confiança (EXTRACTED = explícita na fonte, INFERRED = derivada por resolução), para que você possa distinguir o que foi lido diretamente do que foi inferido. graphify query "<question>" retorna um subgrafo com escopo para uma pergunta em linguagem simples, e graphify path A B traça como duas coisas quaisquer se conectam.

O que ele faz¶

O que você obtém de imediato:

[!TIP] Executando isso em muitos repositórios ou em um monorepo? O Graphify Cloud faz isso continuamente e reduz o gasto de tokens dos agentes em 80%, com links multi-repositório, revisão de código em todo o SDLC, verificação formal e conectores Sentry/Jira. Comece um teste gratuito de 14 dias →

Benchmarks: 0.497 recall@10, 0 LLM credits¶

Todos os sistemas rodaram no mesmo harness com o mesmo modelo e orçamentos, avaliados por um juiz validado às cegas contra um segundo juiz (90.6% de concordância, kappa de Cohen 0.81). Tabelas completas por sistema, o resultado de inteligência de código e comandos de reprodução: BENCHMARKS.md.

Documentação¶

Guias completos e referência ficam em docs.graphify.com:

• Início rápido: construa seu primeiro grafo
• Referência da CLI: todos os comandos e flags
• Faça melhores perguntas ao grafo: padrões de consulta
• Configuração: variáveis de ambiente e ajustes
• Entradas suportadas: linguagens e tipos de arquivo
• Fluxos de equipe e Revisão de PR
• Solução de problemas e Como funciona

Pré-requisitos¶

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

Install¶

[!IMPORTANT] Pacote oficial: O pacote no PyPI é graphifyy (com y duplo). Outros pacotes graphify* no PyPI não são afiliados. O comando da CLI continua sendo graphify.

O repositório oficial de código-fonte é Graphify-Labs/graphify.

O início rápido de dois comandos está no topo deste README. Esta seção cobre os métodos de instalação, instalações com escopo de projeto e todas as plataformas suportadas.

Métodos de instalação (escolha um):

uv tool install graphifyy   # recommended, isolated env (if 'graphify' isn't found after, run: uv tool update-shell)
pipx install graphifyy      # alternative
pip install graphifyy       # may need PATH setup, see Troubleshooting below

Depois execute graphify install uma vez. Ele detecta qual assistente você usa e registra a skill, então não há configuração por assistente. Abra seu assistente de IA e digite /graphify .

Para instalar a skill do assistente no repositório atual em vez do seu perfil de usuário, adicione --project:

graphify install --project
graphify install --project --platform codex

Instalações com escopo de projeto gravam no diretório atual, por exemplo .claude/skills/graphify/SKILL.md ou .agents/skills/graphify/SKILL.md (além de um sidecar references/ que a skill carrega sob demanda), e imprimem uma dica de git add para arquivos que podem ser commitados. Comandos por plataforma que suportam instalações com escopo de projeto aceitam a mesma flag, por exemplo graphify claude install --project ou graphify codex install --project.

[!TIP] Esbarrou em command not found, um problema de pip no Mac/Windows, aspas no PowerShell, uso de uvx, peculiaridades de PATH em git-hook ou modo estrito? Veja Instalação e Solução de problemas.

Faça seu assistente sempre usar o grafo¶

Execute isto uma vez no seu projeto depois de construir um grafo:

Execute graphify <platform> install uma vez no seu projeto, por exemplo graphify claude install ou graphify codex install (ou graphify install --platform <name>).

Isso grava um pequeno arquivo de configuração que diz ao seu assistente para consultar o grafo de conhecimento em perguntas sobre a base de código, preferindo consultas com escopo como graphify query "<question>" em vez de ler o relatório completo ou fazer grep em arquivos brutos.

• Plataformas com hook (Claude Code, Gemini CLI): um hook dispara automaticamente antes de chamadas de ferramenta de busca (e, no Claude Code, antes de ler arquivos-fonte um a um via as ferramentas Read/Glob) e empurra seu assistente para o caminho do grafo.
• Plataformas com arquivo de instruções (Codex, OpenCode, Cursor, etc.): arquivos de instrução persistentes (AGENTS.md, .cursor/rules/, etc.) fornecem a mesma orientação de consulta em primeiro lugar.

O GRAPH_REPORT.md continua disponível para revisão ampla de arquitetura.

Exatamente quais arquivos cada plataforma grava (o CODEBUDDY.md + hooks PreToolUse do CodeBuddy, o AGENTS.md do Codex, o plugin nativo .kilo do Kilo, a regra alwaysApply do Cursor, e assim por diante) é coberto em Configuração sempre ativa.

Para remover o graphify de todas as plataformas de uma vez: graphify uninstall (adicione --purge para também excluir graphify-out/). Ou use o comando por plataforma (por exemplo, graphify claude uninstall).

Skills de CLI ou instruções de MCP?¶

As instruções instaladas por graphify install e aquelas fornecidas com uma conexão MCP do Graphify descrevem maneiras diferentes de consultar um grafo:

Ambas incentivam consultas com escopo ao grafo antes de buscas amplas na fonte. Escolha as instruções que correspondem às ferramentas que seu assistente realmente consegue acessar; nenhum dos blocos estabelece uma regra universal de precedência para os arquivos de instrução do seu assistente. Se você usa as duas integrações, identifique qual grafo cada uma consulta e escolha um caminho de consulta principal em vez de copiar dois blocos de instrução incondicionais no AGENTS.md.

graphify install instala a integração local do assistente; ele não estabelece uma conexão MCP. Um cliente MCP não precisa executar consultas locais da CLI para usar seu servidor conectado. Um servidor hospedado localmente ainda precisa da própria instalação e grafo do Graphify, enquanto uma conexão hospedada pode servir um grafo que não está presente no diretório de trabalho do cliente. Se as ferramentas esperadas estiverem faltando, verifique a instalação relevante da CLI ou a conexão MCP em vez de tratar as instruções da outra configuração como intercambiáveis.

O que há no relatório¶

O GRAPH_REPORT.md resume os god nodes, as comunidades e os caminhos principais para revisão ampla de arquitetura. Como o grafo é construído e o que ele contém: Como o graphify funciona.

Quais arquivos ele processa: ~40 languages¶

O graphify analisa ~40 linguagens de programação localmente com AST do tree-sitter, e mapeia documentos, PDFs, imagens e áudio/vídeo através de uma passagem semântica opcional. Lista completa: Entradas suportadas.

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 commit + branch checkout (run `graphify update .` after `git pull`: see "Recommended workflow" below)
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¶

O graphify respeita .gitignore e suporta padrões --exclude e um .graphifyignore de projeto. Detalhes: Configuração.

Configuração do projeto¶

Crie um .graphifyrc na raiz da varredura para configurações que pertencem ao projeto e não a uma única execução. Um key=value por linha; linhas começando com # são comentários.

Extensões ambíguas. Algumas extensões significam linguagens diferentes em projetos diferentes: .inc é PHP no pfSense, Pascal em uma árvore Delphi, SQL ou assembly em outros lugares; .h é C ou C++; .m é Objective-C ou MATLAB. O graphify tem que escolher um padrão global, e quando escolhe errado o arquivo não falha: ele é analisado como a linguagem errada e produz um punhado de nós incidentais, então o grafo parece populado enquanto os símbolos reais estão faltando. Declare o que a extensão significa no seu repositório:

# .graphifyrc
# A language name:
language.inc=php
# Or an extension graphify already knows:
language.tpl=.ts
# Baked into the git hooks (see Team setup):
viz_node_limit=0

A declaração flui pela classificação, seleção de extrator, gramática e resolução, importações, graphify watch e o cache de AST (um arquivo reanalisado sob uma linguagem diferente nunca reutiliza a entrada antiga), e o mesmo .graphifyrc é lido por extract, update, os hooks, o servidor MCP e a skill /graphify. Um erro de digitação é reportado uma vez no stderr e a varredura continua com os padrões. Como as declarações interagem com cache, reconstruções incrementais e resolução de importações: Configuração.

Configuração de equipe¶

Faça commit ou compartilhe o grafo para que toda a sua equipe consulte o mesmo contexto, e revise pull requests com contexto do grafo. Veja Compartilhe contexto com sua equipe e Revise pull requests.

Usando o grafo diretamente¶

Além do seu assistente de IA, consulte graph.json diretamente da CLI com graphify query, graphify path e graphify explain. Um nome que corresponde a vários nós é recusado com os candidatos listados em vez de adivinhado. Scripts podem ler o resultado pelo código de saída: 0 uma resposta, 3 um nome ambíguo, 4 nenhum nó correspondente. Veja Faça melhores perguntas ao grafo e a referência de query.

Variáveis de ambiente¶

Backends, chaves de API, comportamento de hooks e ajustes são controlados por variáveis de ambiente. Tabela completa: Configuração.

Privacidade¶

• Arquivos de código: processados localmente via tree-sitter. Nada sai da sua máquina. Um corpus somente de código não requer chave de API: graphify extract roda totalmente offline. Em um repositório misto, adicione --code-only para indexar apenas o código e pular os docs/PDFs/imagens que de outra forma precisariam de uma LLM.
• 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 a skill /graphify, usando qualquer modelo que sua sessão de 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 Ollama em execução (OLLAMA_BASE_URL), credenciais AWS via a cadeia de provedores padrão (Bedrock - sem chave de API necessária, usa IAM), ou o binário da CLI claude (Claude Code - sem chave de API necessária, usa sua assinatura do Claude). A flag --dedup-llm usa a mesma chave.
• Residência de 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 --backend explícita. Kimi (MOONSHOT_API_KEY) roteia para servidores da Moonshot AI na China.
• Sem telemetria, sem rastreamento de uso, sem analytics.
• Registro de consultas: cada chamada 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 de subgrafo não são armazenadas por padrão. Defina GRAPHIFY_QUERY_LOG_DISABLE=1 para optar por não participar, ou GRAPHIFY_QUERY_LOG=/dev/null para silenciar sem desativar o caminho de código.

Solução de problemas¶

Problemas comuns de instalação e extração e suas correções: Solução de problemas.

Full command reference¶

Todos os comandos e flags, com exemplos: Referência da CLI.

Saiba mais¶

• docs.graphify.com: documentação completa: guias, referência de comandos e integrações
• Como funciona: o pipeline de extração, detecção de comunidades, pontuação de confiança, benchmarks
• ARCHITECTURE.md: detalhamento de módulos, como adicionar uma linguagem
• Integrações opcionais: Docker MCP Toolkit + SQLite
• The Memory Layer: o livro sobre as ideias por trás do graphify, a arquitetura de ponta a ponta

Graphify Cloud¶

O Graphify Cloud é a camada sempre ativa construída sobre o graphify. Em vez de um grafo que você reconstrói sob demanda por pasta, ele mantém um grafo ativo em todo o seu ciclo de vida de desenvolvimento de software:

• 80% menos tokens: memória sempre ativa significa que seus agentes param de reler e reexplicar a base de código a cada sessão.
• Monorepo e multi-repositório: um grafo conectado em cada serviço e repositório, não um grafo por pasta.
• Verificação formal: verifique invariantes de arquitetura e de dependências contra o grafo ativo.
• Revisão de código com uma visão panorâmica do seu SDLC: veja como uma mudança se propaga por todo o sistema antes de fazer o merge.
• Conectores de SDLC: traga Sentry, Jira e mais, para que incidentes, tickets e código vivam em um único grafo.
• Sempre ativo: atualiza continuamente em segundo plano em código, docs e reuniões.

Comece um teste gratuito de 14 dias em app.graphify.com →

Contribuindo¶

Contribuições são bem-vindas. Veja CONTRIBUTING.md para a configuração de desenvolvimento, os comandos de teste e de paridade com a CI, o fluxo de trabalho do git, e o que faz uma contribuição forte (exemplos resolvidos e relatórios de bugs de extração são os mais úteis). Arquitetura e como adicionar uma linguagem: ARCHITECTURE.md.

Novo por aqui? Diga oi no Discord ou nas GitHub Discussions.

Colaboradores¶

Feito com contrib.rocks.

Traduções¶

O README está disponível em 32 idiomas. Use o seletor de idiomas no topo deste arquivo para lê-lo no seu, ou navegue em docs/translations/. Para melhorar uma tradução ou adicionar uma nova, abra um pull request contra o arquivo correspondente lá.

Construindo sobre o graphify¶

Está construindo algo no ecossistema do graphify? Isso é incentivado. Se o seu projeto usa "graphify" no nome (por exemplo graphify-dashboard ou graphify-action), adicione uma breve nota ao seu README esclarecendo que é feito pela comunidade e não é afiliado nem endossado pela Graphify Labs. "graphify" e o logo do graphify são marcas da Graphify Labs; não os use de uma forma que implique status oficial.

Comunidade e links¶