repo2graph

---

⚡ ¿Qué es repo2graph?

Cuando un agente de IA busca en un código con grep o coincidencia de palabras clave, o bien vuelca archivos completos en el contexto — quemando el presupuesto de tokens y perdiendo la estructura — o pierde la implementación por completo porque usó palabras diferentes a las de la consulta.

repo2graph analiza el código fuente con tree-sitter y lo convierte en un grafo de relaciones reales de código — CALLS, IMPORTS, INHERITS, DEFINES, CO_CHANGE — y sirve ese grafo a los agentes a través del Model Context Protocol, o lo empaqueta en un contexto markdown con límite de presupuesto para cualquier LLM. Cada bloque devuelto lleva un ancla exacta de [cite: path:start-end], de modo que las respuestas se pueden rastrear hasta el código fuente en lugar de parafrasearse a partir de una suposición.

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]

Sin configuración de proyecto, sin servidor de lenguaje, sin paso de compilación — apúntalo a una carpeta y funciona.

Lienzo interactivo, con zoom	Controles de filtro e inspección

graph.html es un único archivo autocontenido — sin servidor, sin internet, arrastra para desplazarte, desplázate para hacer zoom, haz clic en un nodo para inspeccionar su código y sus vecinos.

🚀 Inicio rápido (menos de 30 segundos)

Requiere Python 3.10+. Ejecuta con uv, sin paso de instalación:

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

O instálalo correctamente:

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

Una sola pasada sobre este repositorio — 185 archivos — tarda unos dos segundos y no necesita archivo de configuración, ni servidor de lenguaje, ni clave de API. Pregúntale algo, y la respuesta vuelve como código fuente que puedes verificar, no como un resumen en el que tienes que confiar:

🔌 Configuración del cliente MCP

repo2graph-mcp es un servidor MCP stdio. Construye su propio índice en la primera llamada si no existe todavía — no hay nada que ejecutar de antemano.

Claude Code

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

Claude Desktop (claude_desktop_config.json) y Cursor (.cursor/mcp.json) — el mismo bloque:

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

Cualquier otro cliente MCP basado en stdio (Windsurf, Zed, clientes genéricos) usa el mismo par command/args — consulta docs/mcp.md para las ubicaciones de los archivos de configuración según la plataforma y el cliente.

Ese es el salto que grep no puede hacer: un símbolo de entrada, y su definidor, sus llamadores y sus llamados vuelven con archivo y línea — la relación, no una coincidencia de texto que casualmente contiene el nombre.

✨ Características clave

Grafo determinista, no solo búsqueda por embeddings	Llamadores, llamados, importaciones y jerarquías de clases resueltos desde el AST real — no una suposición de vecino más cercano.
Recuperación híbrida	BM25 + expansión de vecinos del grafo por defecto; fusión densa de vectores opcional (repo2graph embed) sin dependencias adicionales requeridas.
Límites duros de tokens, aplicados dos veces	El presupuesto de pack_context() limita el markdown completo renderizado, no solo el texto de los fragmentos — y el servidor MCP ajusta y vuelve a medir antes de devolver.
15 lenguajes, tratamiento completo	Python, JS/TS/TSX, Go, Rust, Java, Ruby, C, C++, C#, PHP, Kotlin, Swift, Scala, Bash obtienen funciones/clases/llamadas. Todo lo demás aparece como archivos en el mapa.
Nativo para CI	Publicado como GitHub Action — confirma un grafo nuevo junto a tu código en cada push.
Local por defecto	build, query, rag y el servidor MCP hacen cero llamadas de red. La única excepción opcional (rag --answer) imprime el proveedor y el hostname antes de enviar nada.
Exportación a herramientas de grafos reales	graph.graphml (yEd, Gephi, NetworkX) y graph.cypher (Neo4j, Memgraph) salen de cada compilación, sin paso adicional.

🆚 Cómo se compara

Varias herramientas construyen un grafo a partir de un código. Lo que las diferencia es lo que vuelve cuando haces una pregunta — una imagen, un subgrafo, o el código mismo.

	repo2graph	Graphify	Code Graph (Obsidian)	grep / RAG por embeddings
Lo que devuelve una consulta	el código fuente, empaquetado — cada bloque encabezado por [cite: path:start-end]	un subgrafo acotado, una ruta, o una explicación de concepto para recorrer	una imagen de fuerza dirigida para leer	líneas coincidentes, o fragmentos de vecino más cercano
Cómo se clasifican los resultados	semillas BM25, luego expansión de grafo k-hop; fusión densa opcional	recorrido de grafo (explícitamente no un índice vectorial)	n/a — es una vista	solo léxico, o solo vectores
Presupuesto de tokens	límite duro en el paquete completo, re-medido antes de devolver (techo de 12k sobre MCP)	no es una capa de empaquetado	n/a	normalmente sin límite
Aristas desde historial de git	CO_CHANGE, desde --git-history	—	—	—
Funciona sin asistente, sin modelo, sin cuenta	sí — CLI, MCP, o la GitHub Action	la pasada de código es local; la pasada de docs/media usa un modelo	necesita Obsidian desktop 1.7.2+	varía
Corpus	código en 15 lenguajes analizados, todos los demás archivos como texto	código en ~40 lenguajes, más docs, PDFs, imágenes, video	TS/TSX/JS/Python analizados, solo importaciones para 8 más	cualquier cosa

Usa Graphify cuando el grafo en sí es el producto: detección de comunidades, camino más corto entre dos conceptos, y tus PDFs y documentos de diseño en el mismo grafo que el código. Usa el plugin de Obsidian cuando un humano quiere leer el grafo junto a sus notas. Usa repo2graph cuando un agente necesita código fuente citado dentro de un presupuesto fijo de tokens, cuando tiene que ejecutarse en CI sin modelo y sin cuenta, o cuando "qué archivos cambian juntos" es parte de la respuesta.

Versión más larga, con las compensaciones que implica cada elección: docs/comparison.md.

🛠️ Herramientas MCP expuestas

Herramienta	Argumentos	Lo que devuelve
repo_map	ninguno	Lenguajes, archivos centrales y puntos de entrada principales. Estable entre llamadas — léelo primero.
repo_search	query, k opcional (por defecto 8, máximo 50), hops (por defecto 1, máximo 4), budget_tokens (por defecto 6000, máximo 12000)	Fragmentos semilla más vecinos del grafo, cada bloque encabezado por [cite: path:start-end].
repo_neighbours	node_id, hops opcional (máximo 4), limit (por defecto 20, máximo 50)	Un salto de grafo desde un id de símbolo/archivo/directorio: llamadores, llamados, clases base, archivo definidor.

Los secretos se excluyen incondicionalmente en cada llamada de herramienta — ninguna bandera lo desactiva. Contrato completo, incluyendo las dos herramientas de diagnóstico (repo_cache_stats, repo_build_status) añadidas para despliegues de servidor de larga duración: docs/mcp.md.

📐 Arquitectura y economía de tokens

• Nodos: repo, dir, file, symbol (función/método/clase/struct/trait/interfaz/tipo), module (dependencia externa), external (un objetivo de llamada no resuelto).
• Aristas: CONTAINS, DEFINES, IMPORTS, CALLS (lleva count + confidence), CALLS_EXTERNAL, INHERITS, CO_CHANGE (desde --git-history, requiere 3+ co-ediciones).
• La resolución de llamadas se basa en nombres, no en tipos — una compensación deliberada que mantiene a repo2graph agnóstico de lenguaje y sin configuración. Las llamadas ambiguas se ramifican hasta 5 aristas candidatas en confidence = 1/n; filtra a confidence == 1.0 cuando necesites certeza sobre recuperación.
• Dos modelos de presupuesto, a propósito: el budget_chars de Index.retrieve() limita solo el texto de los fragmentos (una superficie de compatibilidad hacia atrás); el budget_chars de Index.pack_context() limita el markdown completo renderizado — encabezados de citas, separadores, todo. El nuevo código de recuperación debería construirse sobre pack_context().
• Fragmentación: aproximadamente un fragmento por función/clase, cortado a ~4000 caracteres con 8 líneas de solapamiento para que nada se pierda en una costura; el encabezado de cada fragmento nombra sus llamadores y llamados, que es lo que hace que la recuperación expandida por grafo sea mejor que la búsqueda de texto top-k simple.

Desglose completo de cada tipo de nodo/arista y el esquema de fragmentos: docs/reference.md. El pipeline, la API de Python, y dónde el grafo adivina (y por qué): TECHNICAL.md.

📊 Míralo en repositorios reales

No es una demo de juguete — cinco repositorios públicos reales y grandes, cada uno indexado en un commit fijado, con el grafo generado confirmado y el comando de reproducción exacto registrado. Cada número se mide, desde benchmarks/results.json, no se estima.

Repositorio	Lenguaje(s)	Alcance	Nodos	Aristas
Kubernetes	Go	acotado (controllers, scheduler, API server)	14,197	83,525
TensorFlow	C++ / Python	acotado (frontera Python/C++)	20,641	96,013
Django	Python	repositorio completo	54,544	228,461
VS Code	TypeScript	acotado (src/vs/)	113,115	431,453
Linux kernel	C	acotado (escala extrema)	136,182	257,655

Consulta examples/README.md para el índice completo y los comandos de reproducción, docs/benchmarks.md para la metodología, y docs/limitations.md para lo que ejecutar contra cinco repositorios reales realmente sacó a la luz (tasas de error de análisis en C/C++ con muchos macros, ambigüedad de nombres de llamadas, límites de resolución entre lenguajes).

📖 Referencia de CLI y servidor

Comando	Hace
repo2graph build <path> -o .r2g [--git-history N]	Analiza un repositorio local en un grafo + fragmentos.
repo2graph github <owner/repo> -o <dir>	Obtiene, construye y limpia — sin necesidad de clon local.
repo2graph query "<question>" -o .r2g	Búsqueda léxica + expansión de grafo de un salto.
repo2graph rag "<question>" -o .r2g [--vectors] [--answer]	Paquete GraphRAG con límite de presupuesto; --answer lo envía a un LLM (opt-in, red).
repo2graph embed -o .r2g [--verify-rag]	Calcula/verifica vectores densos para búsqueda híbrida.
repo2graph map -o .r2g [--viz-nodes N]	Regenera graph.html con un límite de nodos diferente.
repo2graph stats -o .r2g	Conteos de nodos/aristas/funciones para un índice existente.
repo2graph-mcp <path> [--no-auto-build] [--async-build]	Servidor MCP stdio sobre .r2g.

Variables de entorno (solo las lee rag --answer, en este orden de precedencia): GEMINI_API_KEY → OPENAI_API_KEY → ANTHROPIC_API_KEY → OLLAMA_HOST. --model anula el valor por defecto de mejor esfuerzo del proveedor. Ningún otro comando hace una llamada de red ni lee estas. Tablas completas de banderas y contabilidad de presupuesto: docs/cli.md.

🔐 Seguridad

build, query, rag y el servidor MCP no realizan llamadas de red. rag --answer es la única excepción opcional: envía el paquete ensamblado a un proveedor de LLM e imprime el proveedor y el nombre de host antes de hacerlo. El servidor MCP excluye archivos con forma de credenciales de forma incondicional, sin ninguna opción para desactivarlo. Detalles: SECURITY.md.

🤝 Contribución y comunidad

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 — configuración completa de desarrollo local, estilo de código y el proceso de publicación en el registro/Glama.
• docs/BACKLOG.md — trabajo deliberadamente diferido y por qué; lo más parecido a una hoja de ruta, además de una sección de "buenas primeras contribuciones".
• AGENTS.md — convenciones no obvias de este código (codificación de Windows, división de texto, los dos modelos de presupuesto) antes de editar repo2graph/.
• CODE_OF_CONDUCT.md — Contributor Covenant v2.1.
• ¿Encontraste un error o tienes una idea de funcionalidad? Abre un issue.

Licencia

MIT. Consulta LICENSE.

---