repo-graph

Memoria de grafo estructural para asistentes de programación por IA. Mapea tu base de código. Navega por estructura. Lee solo lo que importa.

repo-graph proporciona a los LLM un mapa de tu base de código —entidades, relaciones y flujos— para que puedan navegar a los archivos correctos sin tener que leer todo primero.

En lugar de inundar la ventana de contexto de un LLM con toda tu base de código (o esperar que adivine correctamente), repo-graph construye un grafo ligero de lo que existe, cómo se conectan las cosas y dónde están los puntos de entrada. El LLM consulta el grafo, encuentra el conjunto mínimo de archivos que necesita y lee solo esos.

Demo

https://github.com/user-attachments/assets/a1e4171b-b225-40d4-9210-39453e14b76a

https://github.com/user-attachments/assets/fc3191e5-fc35-4bd7-8372-72af55995883

Mismo error, mismo modelo, mismo prompt: la única diferencia es si repo-graph está instalado.

La tarea: corregir un operador de comparación invertido en un monorepo de Go + Angular (566 nodos, 620 aristas).

2.5 veces menos tokens. ~9 veces más rápido. La misma corrección correcta.

Cómo se ejecutó la prueba

Ambas ejecuciones utilizaron condiciones idénticas para mantener la comparación justa:

• Mismo modelo: Claude Opus, 100% (sin enrutamiento Haiku)

• Mismo prompt: "Los grupos que se crearon recientemente aparecen como cerrados, y los grupos antiguos aparecen como abiertos. Esto está al revés: los grupos nuevos deberían estar abiertos para que los miembros se unan. Encuentra y corrige el error."

• Contexto nuevo: cada ejecución comenzó desde /clear sin conversación previa

• Sin otras herramientas: CLAUDE.md, plugins, hooks y todos los demás servidores MCP fueron eliminados para ambas ejecuciones; la única variable fue si repo-graph estaba instalado

• Sin pistas: el prompt describe el síntoma, no la ubicación; Claude tiene que encontrar group_controller.go:57 por su cuenta

Sin repo-graph, Claude busca palabras clave con grep, lee archivos, vuelve a buscar, lee más archivos y finalmente reduce el alcance hasta el error. Con repo-graph, Claude llama a flow("groups"), obtiene exactamente la función manejadora y el archivo, lo lee y lo corrige.

Explora ejemplos pregenerados para FastAPI, Gin, Hono y NestJS: salida de grafo real que puedes inspeccionar sin instalar nada.

El problema

Los LLM que trabajan con código desperdician la mayor parte de su contexto en la orientación:

• Leer archivos que resultan ser irrelevantes

• Perder conexiones entre componentes en diferentes lenguajes

• No saber dónde comienza una característica o qué toca

• Cargar 50 archivos cuando 5 serían suficientes

Esto es costoso, lento y empeora a medida que crecen las bases de código.

Cómo lo resuelve repo-graph

repo-graph escanea tu base de código una vez y construye un grafo de:

• Entidades: módulos, paquetes, clases, funciones, rutas, servicios, componentes

• Relaciones: importaciones, llamadas, manejadores, definiciones, contenedores

• Flujos: rutas de extremo a extremo desde el punto de entrada hasta la capa de datos

Luego expone 12 herramientas MCP que permiten al LLM:

1. Orientarse — "¿Qué lenguajes hay en este repositorio? ¿Cuáles son las características principales?"

2. Navegar — "Rastrea el flujo de inicio de sesión desde la ruta hasta la base de datos" / "¿Cuál es el camino más corto entre UserService y la API de pagos?"

3. Delimitar — "¿Cuántas líneas tendría que leer para entender esta característica?" / "Dame solo los archivos que necesito para esta corrección de error"

4. Evaluar — "¿Cuál es el radio de impacto de cambiar esta función?" / "¿Qué archivos representan los mayores riesgos de mantenimiento?"

El LLM obtiene contexto estructural en unos pocos cientos de tokens en lugar de leer miles de líneas.

Lenguajes soportados

Se pueden combinar varios analizadores en un mismo repositorio (ej. backend en Go + frontend en Angular + SCSS). Cada uno contribuye con sus nodos y aristas a un único grafo unificado.

Instalación

pip install mcp-repo-graph

Requiere Python 3.11+. Única dependencia de tiempo de ejecución: mcp[cli].

Inicio rápido

1. Generar el grafo

repo-graph-generate --repo /path/to/your/project

Esto escanea la base de código y escribe los datos del grafo en .ai/repo-graph/ dentro del repositorio objetivo.

2. Conectar a tu asistente de IA

Añade a tu configuración de MCP:

Claude Code (~/.claude/claude_code_config.json o .mcp.json del proyecto):

{
  "mcpServers": {
    "repo-graph": {
      "command": "repo-graph",
      "args": ["--repo", "/path/to/your/project"]
    }
  }
}

Con variable de entorno:

{
  "mcpServers": {
    "repo-graph": {
      "command": "repo-graph",
      "env": { "REPO_GRAPH_REPO": "/path/to/your/project" }
    }
  }
}

3. Usarlo

El asistente de IA ahora tiene acceso a las 12 herramientas. Ejemplos de consultas que puede responder:

• "¿Qué hace esta base de código?" -> herramienta status

• "Rastrea el flujo de pago" -> herramienta flow

• "¿Qué se rompería si cambio UserService?" -> herramienta impact

• "¿Qué archivos necesito para este error?" -> herramienta minimal_read

• "Este archivo es demasiado grande, ¿cómo debería dividirlo?" -> herramienta split_plan

• "Muéstrame el flujo de autenticación visualmente" -> herramienta graph_view

4. Mantenerlo actualizado con un git hook (recomendado)

Añade repo-graph-generate a un hook de pre-commit para que el grafo se mantenga actualizado automáticamente; no se gasta contexto del LLM en la regeneración:

# .git/hooks/pre-commit (or add to your existing hook)
#!/bin/sh
repo-graph-generate --repo .
git add .ai/repo-graph/

chmod +x .git/hooks/pre-commit

Cada commit mantiene el grafo al día. El LLM siempre tiene un mapa fresco sin desperdiciar ni un solo token en generate.

Consejo: Si no quieres datos de grafo en el control de versiones, añade .ai/repo-graph/ a .gitignore y omite la línea git add; el grafo simplemente vivirá localmente.

Referencia de herramientas MCP

Generación

Navegación

Presupuesto de contexto

Análisis de salud

Cómo funciona

1. Detectar — scan_project_dirs() encuentra las raíces del proyecto (incluyendo diseños de monorepo como packages/*, apps/*, services/*, src/*). Cada analizador busca sus archivos marcadores.

2. Escanear — los analizadores coincidentes extraen entidades y relaciones usando heurísticas de expresiones regulares. Sin análisis AST, sin cadenas de herramientas externas, sin paso de compilación requerido.

3. Fusionar — todos los resultados de los analizadores se fusionan en un único grafo. Los nodos se desduplican por ID, las aristas por (desde, hacia, tipo).

4. Servir — el servidor MCP carga el grafo en memoria y expone herramientas de recorrido basadas en BFS.

Formato de datos del grafo

Los archivos generados viven en .ai/repo-graph/ dentro del repositorio objetivo:

• nodes.json — [{id, type, name, file_path}, ...]

• edges.json — [{from, to, type}, ...]

• flows/*.yaml — flujos de características nombrados con secuencias de pasos ordenadas

• state.md — instantánea legible por humanos para una orientación rápida

Tipos de aristas: imports, defines, contains, uses, calls, handles, handled_by, exports, includes.

Añadir un nuevo analizador

Crea repo_graph/analyzers/<lenguaje>.py:

from .base import AnalysisResult, Edge, LanguageAnalyzer, Node, scan_project_dirs, rel_path, read_safe

class MyLangAnalyzer(LanguageAnalyzer):

    @staticmethod
    def detect(repo_root):
        # Check for language marker files
        return any(
            (d / "my-marker").exists()
            for d in scan_project_dirs(repo_root)
        )

    def scan(self):
        nodes, edges = [], []
        # ... scan files, extract entities, build relationships ...
        return AnalysisResult(
            nodes=nodes,
            edges=edges,
            state_sections={"MyLang": f"{len(nodes)} entities\n"},
        )

    # Optional: file-level analysis for bloat_report / split_plan
    def supported_extensions(self):
        return {".mylang"}

    def analyze_file(self, file_path):
        # Return dict with function/method sizes, class counts, etc.
        pass

    def format_bloat_report(self, analysis):
        # Format the analysis dict into a human-readable string
        pass

Regístralo en analyzers/__init__.py añadiéndolo a _analyzer_classes().

Licencia

MIT

Soporte

Si repo-graph te ahorró tiempo, considera invitarme a un café.