repo2graph

---

⚡ O que é repo2graph?

Quando um agente de codificação de IA pesquisa um código com grep ou correspondência simples de palavras-chave, ele ou despeja arquivos inteiros correspondentes no contexto — queimando o orçamento de tokens e perdendo a estrutura — ou perde a implementação completamente porque usou palavras diferentes da consulta de pesquisa.

repo2graph analisa o código-fonte com tree-sitter em um grafo de relações reais de código — CALLS, IMPORTS, INHERITS, DEFINES, CO_CHANGE — e serve esse grafo a agentes através do Model Context Protocol, ou o empacota em um contexto markdown com orçamento limitado para qualquer LLM. Cada bloco retornado carrega uma âncora exata [cite: path:start-end], então as respostas são rastreáveis de volta ao código-fonte em vez de parafraseadas a partir de uma suposição.

flowchart LR
    A[your code] --> B[tree-sitter<br/>reads the code]
    B --> C[graph<br/>dots + arrows]
    C --> D[graph.html<br/>the picture]
    C --> E[chunks.jsonl<br/>pieces for an AI]
    C -->|MCP stdio| F[Claude / Cursor /<br/>any MCP client]

Sem configuração de projeto, sem servidor de linguagem, sem etapa de build — aponte para uma pasta e funciona.

Canvas interativo, com zoom	Controles de filtro e inspeção

graph.html é um arquivo autônomo — sem servidor, sem internet, arraste para mover, role para dar zoom, clique em um nó para inspecionar seu código e vizinhos.

🚀 Início rápido (em menos de 30 segundos)

Requer Python 3.10+. Execute via uv, sem etapa de instalação:

uvx repo2graph build . -o .r2g && open .r2g/human/graph.html

Ou instale corretamente:

pip install repo2graph
repo2graph build /path/to/project -o .r2g --git-history 200
repo2graph query "how does routing match a path" -o .r2g

Uma passada sobre este repositório — 185 arquivos — leva cerca de dois segundos e não precisa de arquivo de configuração, servidor de linguagem ou chave de API. Pergunte algo, e a resposta volta como código-fonte que você pode verificar, não um resumo em que você precisa confiar:

🔌 Configuração do cliente MCP

repo2graph-mcp é um servidor MCP stdio. Ele constrói seu próprio índice na primeira chamada se um não existir ainda — nada para executar antecipadamente.

Claude Code

claude mcp add repo2graph -- uvx --from "repo2graph[mcp]" repo2graph-mcp /path/to/project

Claude Desktop (claude_desktop_config.json) e Cursor (.cursor/mcp.json) — mesmo bloco:

{
  "mcpServers": {
    "repo2graph": {
      "command": "uvx",
      "args": ["--from", "repo2graph[mcp]", "repo2graph-mcp", "/path/to/project"]
    }
  }
}

Qualquer outro cliente MCP baseado em stdio (Windsurf, Zed, clientes genéricos) aceita o mesmo par command/args — veja docs/mcp.md para locais de arquivos de configuração por plataforma e cliente.

Esse é o salto que o grep não consegue fazer: um símbolo de entrada, e seu definidor, seus chamadores e seus chamados voltam com arquivo e linha — a relação, não uma correspondência de texto que por acaso contém o nome.

✨ Principais recursos

Grafo determinístico, não apenas busca por embeddings	Chamadores, chamados, importações e hierarquias de classes resolvidos a partir do AST real — não um palpite de vizinho mais próximo.
Recuperação híbrida	BM25 + expansão de vizinhos do grafo por padrão; fusão densa de vetores opcional (repo2graph embed) com zero dependências extras necessárias.
Limites rígidos de tokens, aplicados duas vezes	O orçamento de pack_context() limita o markdown inteiro renderizado, não apenas o texto do chunk — e o servidor MCP limita e re-mede antes de retornar.
15 linguagens, tratamento completo	Python, JS/TS/TSX, Go, Rust, Java, Ruby, C, C++, C#, PHP, Kotlin, Swift, Scala, Bash recebem funções/classes/chamadas. Todo o resto ainda aparece como arquivos no mapa.
Pronto para CI	Publicado como GitHub Action — comprometa um grafo atualizado ao lado do seu código a cada push.
Local por padrão	build, query, rag e o servidor MCP fazem zero chamadas de rede. A única exceção opcional (rag --answer) imprime o provedor + hostname antes de enviar qualquer coisa.
Exportação para ferramentas de grafo reais	graph.graphml (yEd, Gephi, NetworkX) e graph.cypher (Neo4j, Memgraph) saem de cada build, sem etapa extra.

🆚 Como se compara

Várias ferramentas constroem um grafo a partir de um código. O que as separa é o que volta quando você faz uma pergunta — uma imagem, um subgrafo ou o próprio código.

	repo2graph	Graphify	Code Graph (Obsidian)	grep / RAG por embeddings
O que uma consulta retorna	o código-fonte, empacotado — cada bloco encabeçado por [cite: path:start-end]	um subgrafo escopado, um caminho ou uma explicação de conceito para percorrer	uma imagem de força direcionada para ler	linhas correspondentes, ou chunks de vizinho mais próximo
Como os resultados são classificados	sementes BM25, depois expansão de grafo k-hop; fusão densa opcional	travessia de grafo (explicitamente não um índice vetorial)	n/a — é uma visualização	apenas lexical, ou apenas vetores
Orçamento de tokens	limite rígido no pacote inteiro, re-medido antes de retornar (teto de 12k via MCP)	não é uma camada de empacotamento	n/a	geralmente ilimitado
Arestas do histórico do git	CO_CHANGE, de --git-history	—	—	—
Executa sem assistente, sem modelo, sem conta	sim — CLI, MCP ou GitHub Action	a passagem de código é local; a passagem de docs/mídia usa um modelo	precisa do Obsidian desktop 1.7.2+	varia
Corpus	código em 15 linguagens analisadas, todos os outros arquivos como texto	código em ~40 linguagens, além de docs, PDFs, imagens, vídeo	TS/TSX/JS/Python analisados, apenas importações para mais 8	qualquer coisa

Use Graphify quando o grafo em si é o produto: detecção de comunidades, caminho mais curto entre dois conceitos, e seus PDFs e documentos de design no mesmo grafo que o código. Use o plugin Obsidian quando um humano quiser ler o grafo ao lado de suas notas. Use repo2graph quando um agente precisar de código-fonte citado dentro de um orçamento fixo de tokens, quando tiver que rodar em CI sem modelo e sem conta, ou quando "quais arquivos mudam juntos com frequência" fizer parte da resposta.

Versão mais longa, com os trade-offs que cada escolha implica: docs/comparison.md.

🛠️ Ferramentas MCP expostas

Ferramenta	Argumentos	O que retorna
repo_map	nenhum	Linguagens, arquivos centrais e principais pontos de entrada. Estável entre chamadas — leia isso primeiro.
repo_search	query, k opcional (padrão 8, máx. 50), hops (padrão 1, máx. 4), budget_tokens (padrão 6000, máx. 12000)	Chunks de semente mais vizinhos do grafo, cada bloco encabeçado por [cite: path:start-end].
repo_neighbours	node_id, hops opcional (máx. 4), limit (padrão 20, máx. 50)	Um salto no grafo a partir de um id de símbolo/arquivo/dir: chamadores, chamados, classes base, arquivo definidor.

Segredos são excluídos incondicionalmente em toda chamada de ferramenta — nenhuma flag desativa isso. Contrato completo, incluindo as duas ferramentas de diagnóstico (repo_cache_stats, repo_build_status) adicionadas para implantações de servidor de longa duração: docs/mcp.md.

📐 Arquitetura e economia de tokens

• Nós: repo, dir, file, symbol (função/método/classe/struct/trait/interface/tipo), module (dependência externa), external (um alvo de chamada não resolvido).
• Arestas: CONTAINS, DEFINES, IMPORTS, CALLS (carrega count + confidence), CALLS_EXTERNAL, INHERITS, CO_CHANGE (de --git-history, requer 3+ co-edições).
• A resolução de chamadas é baseada em nome, não em tipo — um trade-off deliberado que mantém repo2graph agnóstico de linguagem e sem configuração. Chamadas ambíguas se ramificam para até 5 arestas candidatas em confidence = 1/n; filtre para confidence == 1.0 quando precisar de certeza em vez de recall.
• Dois modelos de orçamento, de propósito: o budget_chars de Index.retrieve() limita apenas o texto dos próprios chunks (uma superfície de compatibilidade reversa); o budget_chars de Index.pack_context() limita o markdown inteiro renderizado — cabeçalhos de citação, separadores, tudo. Novo código de recuperação deve ser construído sobre pack_context().
• Chunking: aproximadamente um chunk por função/classe, cortado em ~4000 caracteres com 8 linhas de sobreposição para que nada se perca em uma emenda; o cabeçalho de cada chunk nomeia seus chamadores e chamados, que é o que torna a recuperação expandida por grafo melhor do que a busca de texto top-k simples.

Divisão completa de cada tipo de nó/aresta e o esquema de chunk: docs/reference.md. O pipeline, a API Python e onde o grafo adivinha (e por quê): TECHNICAL.md.

📊 Veja em repositórios reais

Não é uma demonstração de brinquedo — cinco repositórios públicos reais e grandes, cada um indexado em um commit fixado, com o grafo gerado comprometido e o comando exato de reprodução registrado. Cada número é medido, de benchmarks/results.json, não estimado.

Repositório	Linguagem(ns)	Escopo	Nós	Arestas
Kubernetes	Go	escopado (controllers, scheduler, API server)	14.197	83.525
TensorFlow	C++ / Python	escopado (fronteira Python/C++)	20.641	96.013
Django	Python	repositório completo	54.544	228.461
VS Code	TypeScript	escopado (src/vs/)	113.115	431.453
Linux kernel	C	escopado (escala extrema)	136.182	257.655

Veja examples/README.md para o índice completo e comandos de reprodução, docs/benchmarks.md para metodologia, e docs/limitations.md para o que rodar contra cinco repositórios reais realmente revelou (taxas de erro de análise em C/C++ pesado de macros, ambiguidade de nomes de chamadas, limites de resolução entre linguagens).

📖 Referência de CLI e servidor

Comando	Faz
repo2graph build <path> -o .r2g [--git-history N]	Analisa um repositório local em um grafo + chunks.
repo2graph github <owner/repo> -o <dir>	Busca, constrói e limpa — sem necessidade de clone local.
repo2graph query "<question>" -o .r2g	Busca lexical + expansão de grafo de um salto.
repo2graph rag "<question>" -o .r2g [--vectors] [--answer]	Pacote GraphRAG com orçamento limitado; --answer o envia para um LLM (opt-in, rede).
repo2graph embed -o .r2g [--verify-rag]	Calcula/verifica vetores densos para busca híbrida.
repo2graph map -o .r2g [--viz-nodes N]	Regenera graph.html com um limite de nós diferente.
repo2graph stats -o .r2g	Contagens de nós/arestas/funções para um índice existente.
repo2graph-mcp <path> [--no-auto-build] [--async-build]	Servidor MCP stdio sobre .r2g.

Variáveis de ambiente (apenas lidas por rag --answer, nesta ordem de precedência): GEMINI_API_KEY → OPENAI_API_KEY → ANTHROPIC_API_KEY → OLLAMA_HOST. --model substitui o padrão de melhor esforço do provedor. Nenhum outro comando faz chamada de rede ou lê essas variáveis. Tabelas completas de flags e contabilidade de orçamento: docs/cli.md.

🔐 Segurança

build, query, rag, e o servidor MCP não fazem chamadas de rede. rag --answer é a única exceção opcional — ele envia o pacote montado para um provedor de LLM e imprime o provedor + hostname antes de fazer isso. O servidor MCP exclui arquivos com formato de credencial incondicionalmente, sem nenhuma flag para desativar isso. Detalhes: SECURITY.md.

🤝 Contribuindo & comunidade

git clone https://github.com/Srinivasan-78/repo2graph
cd repo2graph
python3 -m venv .venv && .venv/bin/pip install -e ".[dev]"
make lint test   # or: ruff check . && pytest

• .github/CONTRIBUTING.md — configuração completa de desenvolvimento local, estilo de código e o processo de lançamento do registry/Glama.
• docs/BACKLOG.md — trabalho deliberadamente adiado e o porquê; a coisa mais próxima de um roadmap, além de uma seção de "boas primeiras issues".
• AGENTS.md — as convenções não óbvias deste código (encoding do Windows, fatiamento de texto, os dois modelos de orçamento) antes de editar repo2graph/.
• CODE_OF_CONDUCT.md — Contributor Covenant v2.1.
• Encontrou um bug ou tem uma ideia de funcionalidade? Abra uma issue.

Licença

MIT. Veja LICENSE.

---