code-review-graph: el mapa del código que hace que tu agente lea solo lo que importa

code-review-graph construye un mapa estructural de tu código con Tree-sitter, lo mantiene actualizado de forma incremental y se lo sirve a tu agente por MCP, para que en vez de releer medio proyecto lea solo las partes que le hacen falta. Se instala con pip install code-review-graph y un único comando lo configura en todos los agentes que detecte. Es MIT y funciona en local.

Y ojo, porque este repo hace algo que casi ninguno hace: matiza sus propias cifras. Volveré a eso.

El problema que ataca

Cuando le pides a un agente que revise un cambio, no tiene un modelo mental de tu proyecto: lo reconstruye leyendo archivos. Y como no sabe cuáles importan, tiende a leer de más. Eso se traduce en tres cosas que sí notas: tarda, gasta contexto que luego le falta para razonar, y en proyectos grandes se queda a medias.

La idea aquí es pagar ese coste una sola vez. Se analiza el código, se construye un grafo con la estructura real —qué llama a qué, qué depende de qué— y a partir de ahí las preguntas del agente se responden desde el mapa en lugar de desde una lectura completa.

El dato, y por qué su matiz importa

El titular de su README es contundente: leer el corpus entero de flask cuesta 143.594 tokens y responder desde el grafo cuesta 2.196, unas 71 veces menos. Los datos están recapturados el 2 de agosto de 2026 con la versión 2.3.7.

Pero justo debajo escriben esto, y es la razón por la que me fío del proyecto:

La comparación contra el corpus entero es una cota superior que ningún agente real paga: un agente competente busca identificadores y lee solo los archivos que mejor encajan.

Y van más allá: tienen un segundo test que mide ese escenario realista, y reconocen que en cambios pequeños su otra métrica da ratios por debajo de 1 —es decir, en un cambio de un solo archivo su respuesta puede costar más que leer el diff— porque incluye el radio de impacto y fragmentos de código alrededor.

Eso no es un defecto: es un README que no te vende humo. La conclusión práctica es la correcta: cuanto más grande el proyecto y más amplia la pregunta, más gana; en cambios pequeños puede no compensar.

Cómo instalarlo

Tres comandos:

pip install code-review-graph      # o: pipx install code-review-graph
code-review-graph install          # detecta y configura todos tus agentes
code-review-graph build            # analiza tu código

El del medio es el que ahorra la tarde. Detecta qué herramientas de programación con IA tienes instaladas, escribe la configuración de MCP correcta para cada una, instala los enganches o skills propios de cada plataforma donde se pueda, e inyecta instrucciones para que el agente use el grafo. Después hay que reiniciar el editor.

La lista de compatibles es larga: Codex, Claude Code, Cursor, Windsurf, Zed, Continue, OpenCode, Gemini CLI, Copilot y su CLI, entre otros. Necesita Python 3.10 o superior.

Un apunte que se agradece: la desinstalación es simétrica y solo borra lo suyo. Otros servidores MCP, enganches y skills que tengas configurados se quedan intactos.

Cómo se nota al usarlo

No hay comandos nuevos que aprender: el agente gana herramientas y las usa cuando le convienen. Expone 30 herramientas MCP por defecto, y si vas justo de contexto puedes limitarlas:

code-review-graph serve --tools query_graph_tool,semantic_search_nodes_tool,detect_changes_tool

Ese detalle revela que han pensado en el problema de verdad: 30 herramientas también ocupan contexto. Poder recortar a tres es la diferencia entre ayudar y estorbar.

Donde más se nota es en preguntas de alcance amplio, del tipo "si cambio esta función, ¿qué se rompe?". Sin grafo, el agente adivina o lee mucho. Con grafo, sigue las aristas.

Aplicaciones prácticas

Revisiones antes de fusionar. Es su caso principal y el que mejor rinde: el agente ve el radio de impacto real del cambio, no solo el diff.

Entrar en un proyecto que no conoces. Un mapa estructural es exactamente lo que le falta a alguien que llega nuevo, sea humano o agente.

Proyectos grandes donde el agente se atasca. Si trabajas con IA para programar y notas que en tu repositorio grande el asistente rinde mucho peor que en uno pequeño, este es el motivo y este es el parche.

Cuándo no te compensa

• En proyectos pequeños, donde el agente puede leerse el código entero sin despeinarse. El propio proyecto lo reconoce en sus mediciones.
• Para cambios de un archivo, donde el diff ya es todo el contexto necesario.
• Si no usas MCP, porque es la vía por la que sirve los datos. Hay CLI, pero pierdes lo bueno.
• Tiene unas 83 incidencias abiertas y va rápido de versiones; cuenta con actualizar de vez en cuando.

Preguntas frecuentes

¿Qué es MCP y por qué hace falta aquí?

Es el protocolo por el que un agente accede a datos y herramientas externas. Aquí es la vía por la que el agente consulta el mapa de tu código en lugar de leer archivos sueltos. Sin MCP, el grafo existiría pero el agente no podría preguntarle.

¿Sube mi código a algún sitio?

No. Es local: analiza en tu máquina y guarda el grafo ahí. Otra cosa es el agente que lo consulta, que si es un modelo en la nube sigue sus propias condiciones con lo que le pases.

¿De verdad ahorra 71 veces los tokens?

Frente a leer el proyecto entero, sí, según sus mediciones. Pero ellos mismos avisan de que ese escenario es una cota superior que un agente competente no paga, y de que en cambios pequeños su otra métrica puede quedar por debajo de 1. Gana en proyectos grandes y preguntas amplias.

¿Funciona con Codex además de con Claude Code?

Sí, y con Cursor, Windsurf, Zed, Continue, OpenCode, Gemini CLI y Copilot entre otros. El comando code-review-graph install detecta lo que tienes y escribe la configuración de cada uno.

¿Qué lenguajes soporta?

Usa Tree-sitter para analizar el código, que es la misma tecnología de resaltado y análisis de muchos editores y cubre los lenguajes habituales. Necesita Python 3.10 o superior para ejecutarse, aunque el código que analiza no tiene que ser Python.