code-review-graph: reduce 65x tokens en agentes IA con code intelligence graph

¿Qué es code-review-graph?

code-review-graph (CRG) es un code intelligence graph local-first para MCP y CLI. Parsea tu codebase con Tree-sitter, construye un grafo persistente de nodos (funciones, clases, imports) y aristas (calls, inheritance, test coverage), y lo expone via MCP para que tu asistente IA lea solo lo que importa.

El resultado: reducción mediana de 65x tokens por pregunta (376x en el mejor caso) comparado a feed todo el codebase al modelo. En un repo de ~209.000 source tokens, CRG devuelve ~3.190 tokens por pregunta.

Funciona con 15+ agentes IA — Claude Code, Codex, Cursor, Gemini CLI, Windsurf, Zed, Continue, OpenCode, GitHub Copilot, Antigravity, Qwen, Qoder, Kiro, CodeBuddy — con auto-detección y configuración en un solo comando.

Para qué sirve

Reduce tokens hasta 65x (mediana) y 376x (mejor caso) dando al agente solo los archivos relevantes
Blast-radius analysis: cuando un archivo cambia, traza callers, dependents y tests afectados
30 MCP tools que tu agente usa automáticamente (impact radius, review context, semantic search, architecture overview, detect changes, etc.)
30+ lenguajes: Python, JS/TS/TSX, Go, Rust, Java, C/C++, C#, Ruby, Kotlin, Swift, PHP, Scala, Solidity, Dart, R, Perl, Lua, Objective-C, shell, Elixir, Zig, PowerShell, Julia, Vue/Svelte, Astro, Jupyter notebooks, Terraform, Ansible, SQL, y más
GitHub Action para PR reviews con risk-scoring en CI — local-first, nada sale del runner
Daemon mode para mantener el grafo actualizado en background
Local-first, zero telemetry: nada sale de tu máquina salvo embeddings opt-in
Wiki generation y visualización (HTML interactivo, JSON, GraphML, SVG, Obsidian, Neo4j Cypher)
Multi-repo registry con daemon para watch varios repos simultáneamente

Instalación

Prerrequisitos

Python 3.10+
uv recomendado (el MCP config usa uvx si está disponible)

Quick Start — 3 comandos

pip install code-review-graph
code-review-graph install    # auto-detecta y configura todos los agentes instalados
code-review-graph build      # parsea tu codebase

El comando install detecta qué agentes IA tienes instalados, escribe la configuración MCP correcta para cada uno, instala hooks/skills donde sea soportado, e inyecta instrucciones graph-aware en tus platform rules. Reinicia tu editor después de instalar.

Instalar para una plataforma específica

code-review-graph install --platform claude-code   # Claude Code
code-review-graph install --platform codex          # OpenAI Codex
code-review-graph install --platform cursor         # Cursor
code-review-graph install --platform gemini-cli     # Gemini CLI
code-review-graph install --platform windsurf       # Windsurf
code-review-graph install --platform zed            # Zed
code-review-graph install --platform continue       # Continue
code-review-graph install --platform opencode       # OpenCode
code-review-graph install --platform copilot        # GitHub Copilot (VS Code)
code-review-graph install --platform copilot-cli    # GitHub Copilot CLI
code-review-graph install --platform antigravity    # Antigravity
code-review-graph install --platform qwen           # Qwen
code-review-graph install --platform qoder          # Qoder
code-review-graph install --platform kiro           # Kiro
code-review-graph install --platform codebuddy      # CodeBuddy

Con uv (recomendado)

pipx install code-review-graph
# o
uvx code-review-graph install
uvx code-review-graph build

Desinstalación

code-review-graph uninstall --dry-run   # preview, no escribe nada
code-review-graph uninstall              # preview + confirmación
code-review-graph uninstall --yes        # aplica sin preguntar
code-review-graph uninstall --keep-data  # remove integrations, keep graph DBs

Primer uso

1. Construir el grafo

code-review-graph build

El build inicial toma ~10 segundos para un proyecto de 500 archivos. El grafo se almacena localmente en .code-review-graph/.

2. Verificar estado

code-review-graph status

Muestra estadísticas del grafo: número de nodos, aristas, archivos indexados, lenguajes detectados.

3. Usar con tu agente IA

Abre tu proyecto en tu editor/agent y simplemente pregunta:

Build the code review graph for this project

Tu agente usará los 30 MCP tools automáticamente. No necesitas prompts especiales.

4. Ver token savings

code-review-graph detect-changes --brief

Muestra un panel con cuántos tokens ahorraste:

┌─────────────────────── Token Savings ────────────────────────┐
│ Full context would be: 12,921 tokens                         │
│ Graph context used: 762 tokens                               │
│ Saved: 12,159 tokens (~94%)                                  │
│ Breakdown: Functions 244 · Tests 191 · Risk 244 · Other 83  │
└──────────────────────────────────────────────────────────────┘

Agrega --verify para cross-check contra el tokenizer de GPT-4 (cl100k_base):

code-review-graph detect-changes --brief --verify  # requiere: pip install tiktoken

Comandos principales

code-review-graph build              # Parse entire codebase
code-review-graph update             # Incremental update (changed files only)
code-review-graph status             # Graph statistics
code-review-graph watch              # Auto-update on file changes
code-review-graph visualize          # Interactive HTML graph
code-review-graph visualize --format json     # Export as JSON
code-review-graph visualize --format graphml  # Export as GraphML
code-review-graph visualize --format svg      # Export as SVG
code-review-graph visualize --format obsidian # Export as Obsidian vault
code-review-graph visualize --format cypher   # Export as Neo4j Cypher
code-review-graph wiki               # Generate markdown wiki from communities
code-review-graph detect-changes --brief      # Risk panel + token savings
code-review-graph serve              # Start MCP server
code-review-graph eval               # Run evaluation benchmarks

Cómo funciona

1. Parse con Tree-sitter

Tu repositorio se parsea en un AST con Tree-sitter. Se extraen nodos (funciones, clases, imports) y aristas (calls, inheritance, test coverage).

2. Grafo persistente

El grafo se almacena localmente. En git repos, solo archivos tracked se indexan (git ls-files), así gitignored files se skipean automáticamente.

3. Blast-radius analysis

Cuando un archivo cambia, el grafo traza every caller, dependent y test que podría ser afectado. Tu agente lee solo estos archivos en vez de escanear todo el proyecto.

4. Incremental updates en segundos

Los hooks o watch mode triggerean updates incrementales. El grafo diffea archivos cambiados, encuentra dependents a través de import/call edges, y re-parsea solo los archivos cuyo SHA-256 hash cambió. En un proyecto de ~3.000 archivos (django), un edit de 2 archivos re-indexa en ~2.5 segundos.

5. Query en review time

En vez de feed todo el corpus al modelo, el grafo devuelve un answer-shaped slice: 208.821 source tokens → ~3.190 tokens por pregunta.

30 MCP Tools disponibles

Tu agente IA usa estas tools automáticamente una vez que el grafo está construido:

Categoría	Tools
Build y update	`build_or_update_graph_tool`, `run_postprocess_tool`
Context y review	`get_minimal_context_tool`, `get_review_context_tool`, `get_impact_radius_tool`, `detect_changes_tool`
Query y traverse	`query_graph_tool`, `traverse_graph_tool`, `semantic_search_nodes_tool`, `embed_graph_tool`
Architecture	`get_architecture_overview_tool`, `list_communities_tool`, `get_community_tool`, `list_flows_tool`, `get_flow_tool`, `get_affected_flows_tool`
Insights	`get_hub_nodes_tool`, `get_bridge_nodes_tool`, `get_knowledge_gaps_tool`, `get_surprising_connections_tool`, `get_suggested_questions_tool`
Code quality	`find_large_functions_tool`, `list_graph_stats_tool`
Refactoring	`refactor_tool`, `apply_refactor_tool`
Wiki y docs	`generate_wiki_tool`, `get_wiki_page_tool`, `get_docs_section_tool`
Multi-repo	`list_repos_tool`, `cross_repo_search_tool`

MCP Prompts (5 workflow templates)

review_changes — review de cambios con contexto de impacto
architecture_map — mapa de arquitectura del codebase
debug_issue — debug con blast-radius
onboard_developer — onboarding de nuevos developers
pre_merge_check — check pre-merge con risk scoring

Tool filtering

En entornos con tokens limitados, puedes limitar las tools expuestas:

# Via CLI flag
code-review-graph serve --tools query_graph_tool,semantic_search_nodes_tool,detect_changes_tool

# Via environment variable
CRG_TOOLS=query_graph_tool,semantic_search_nodes_tool code-review-graph serve

Daemon mode — multi-repo en background

Si tu editor no soporta hooks o quieres el grafo fresco sin intervención:

# 1. Registrar repos
crg-daemon add ~/project-a --alias proj-a
crg-daemon add ~/project-b

# 2. Iniciar daemon (background)
crg-daemon start

# 3. Listo — los grafos se mantienen actualizados automáticamente
crg-daemon status              # estado del daemon y watchers
crg-daemon logs --repo proj-a -f  # tail logs de un repo
crg-daemon stop                # parar daemon y watchers

El daemon monitorea ~/.code-review-graph/watch.toml y arranca/para watchers automáticamente. Health checks cada 30 segundos reinician watchers muertos.

GitHub Action — PR reviews con risk-scoring

El mismo analysis corre como composite GitHub Action. Local-first: el grafo se construye y consulta en tu CI runner, sin enviar código a ningún servicio externo.

# .github/workflows/code-review-graph.yml
on:
  pull_request:
permissions:
  contents: read
  pull-requests: write
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: tirth8205/[email protected]
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}

En cada PR, la action postea un sticky comment con:

Funciones con risk-score
Execution flows afectados
Test gaps detectados

Opcional: fail-on-risk input convierte el review en un merge gate.

Benchmarks

Medidos contra 6 repos open-source reales (13 commits total), con SHAs pineados, Leiden community detector con seed fijo, y embeddings determinísticos en CPU — dos runs en máquinas diferentes producen números idénticos.

Métrica	Valor
Reducción mediana por pregunta	~65x
Reducción máxima (fastapi, corpus más grande)	376x
Rango de reducción	36x – 376x
Tokens source típicos (repo grande)	~209.000
Tokens por pregunta con grafo	~3.190
Latencia incremental (3.000 archivos, 2 editados)	~2.5 segundos
Calibración de token savings vs GPT-4	~1% de error

Limitaciones conocidas

Single-file changes pequeños: el contexto del grafo puede exceder naive file reads para edits triviales (overhead es el metadata estructural)
Search quality (MRR 0.35): keyword search encuentra el resultado correcto en top-4 para la mayoría de queries, pero el ranking necesita mejora
Flow detection (33% recall): patrones de Python y PHP/Laravel son los más fuertes; JS y Go necesitan trabajo
Precision vs recall: impact analysis es deliberadamente conservadora — flags archivos que podrían ser afectados, lo que genera algunos false positives

30+ lenguajes soportados

Parser support cubre funciones, clases, imports, call sites, inheritance y test detection:

Python, JavaScript/TypeScript/TSX, Go, Rust, Java, C/C++, C#, VB.NET, Ruby, Kotlin, Swift, PHP, Scala, Solidity, Dart, R, Perl, Lua/Luau, Objective-C, shell scripts, Elixir, Zig, PowerShell, Julia, ReScript, GDScript, Nix, Verilog/SystemVerilog, SQL, Terraform/OpenTofu (.tf), Ansible playbooks/roles/tasks, Vue/Svelte SFCs, Astro, Jupyter/Databricks notebooks (.ipynb), y Perl XS (.xs).

Agregar tu propio lenguaje (sin fork)

Si tu repo usa un lenguaje no cubierto, drop un languages.toml en .code-review-graph/:

[languages.erlang]
extensions = [".erl"]
grammar = "erlang"
function_node_types = ["function_clause"]
class_node_types = ["record_decl"]
import_node_types = ["import_attribute"]
call_node_types = ["call"]

El tree-sitter walker genérico maneja la extracción. Sin code changes, y los lenguajes built-in nunca pueden ser overridden.

Embeddings opcionales

CRG embebe identifiers, signatures, structural context y un bounded first-paragraph docstring summary. No transmite function bodies.

Embeddings locales (default)

pip install "code-review-graph[embeddings]"
# Usa all-MiniLM-L6-v2 localmente

Embeddings cloud (opt-in)

# OpenAI-compatible (OpenAI, Azure, vLLM, LocalAI, Ollama, LiteLLM)
export CRG_OPENAI_BASE_URL=http://127.0.0.1:3000/v1
export CRG_OPENAI_API_KEY=sk-...
export CRG_OPENAI_MODEL=text-embedding-3-small

# Voyage
export VOYAGE_API_KEY=pa-...
export CRG_ACCEPT_CLOUD_EMBEDDINGS=1
code-review-graph embed --provider voyage --model voyage-code-3

# Google Gemini
export GOOGLE_API_KEY=...
pip install "code-review-graph[google-embeddings]"

Tip: evita model IDs -preview / -beta / -exp para uso long-term — pueden cambiar weights o ser deprecados.

Excluir archivos del indexado

Crea un .code-review-graphignore en la raíz del repo:

generated/**
*.generated.ts
vendor/**
node_modules/**

En git repos, los gitignored files se skipean automáticamente. Usa .code-review-graphignore para excluir tracked files.

Dependencies opcionales

pip install "code-review-graph[embeddings]"    # Local vector embeddings
pip install "code-review-graph[google-embeddings]" # Google Gemini embeddings
pip install "code-review-graph[communities]"      # Community detection (igraph)
pip install "code-review-graph[enrichment]"       # Python call-resolution (Jedi)
pip install "code-review-graph[eval]"             # Evaluation benchmarks
pip install "code-review-graph[wiki]"             # Wiki generation with LLM (ollama)
pip install "code-review-graph[all]"              # All optional dependencies

Comparación con alternativas

vs	Diferencia
LSP / language servers	CRG: un grafo persistente cross-language vs daemons per-language. LSP es más preciso per symbol.
RAG / embeddings	CRG: aristas estructurales del AST, no similarity chunks. Embeddings son opcionales y solo asisten search.
grep / agentic search	grep gana en one-hop lookups; el grafo gana en multi-hop (impact radius, callers-of-callers, tests-for, affected flows).
Serena, codegraph, claude-context, repomix	Ver tabla comparativa en FAQ

Cuándo NO usarlo

Repos pequeños donde grep es suficiente
Single-file diffs triviales
One-off questions que no requieren multi-hop analysis

Privacidad

Zero telemetry: nada se envía a ningún servidor
Cloud embeddings son opt-in: debes setear CRG_ACCEPT_CLOUD_EMBEDDINGS=1 explícitamente
Local-first: el grafo se construye y consulta en tu máquina
GitHub Action: corre en tu CI runner, sin enviar código a servicios externos
Embeddings no transmiten function bodies: solo identifiers, signatures, structural context y docstring summary

FAQ

¿Funciona con mi agente IA?

Si soporta MCP, sí. 15+ plataformas soportadas con auto-detección: Claude Code, Codex, Cursor, Gemini CLI, Windsurf, Zed, Continue, OpenCode, GitHub Copilot, Antigravity, Qwen, Qoder, Kiro, CodeBuddy.

¿Cuánto tarda el build inicial?

~10 segundos para un proyecto de 500 archivos. Updates incrementales en ~2.5 segundos para un edit de 2 archivos en un repo de 3.000.

¿Envía mi código a la nube?

No. Zero telemetry. Cloud embeddings son opt-in y solo transmiten identifiers, signatures y docstring summaries — nunca function bodies.

¿Qué lenguajes soporta?

30+ lenguajes incluyendo Python, JS/TS, Go, Rust, Java, C/C++, C#, Ruby, Kotlin, Swift, PHP, Scala, Solidity, Dart, R, y más. Puedes agregar lenguajes custom con languages.toml sin fork.

¿Cómo verifico que está funcionando?

code-review-graph status           # estadísticas del grafo
code-review-graph detect-changes --brief  # panel de token savings
/mcp                                 # en tu agente, verificar MCP server activo

¿Puedo usarlo en CI?

Sí. GitHub Action composite que postea PR reviews con risk-scoring. Opcional fail-on-risk como merge gate.

Conclusión

code-review-graph resuelve un problema real y creciente: a medida que los agentes IA se vuelven estándar, el token waste de re-leer codebases enteros se vuelve insostenible. CRG construye un grafo estructural persistente con Tree-sitter y expone 30 MCP tools que permiten a cualquier agente IA leer solo lo que importa — con una reducción mediana de 65x tokens. Local-first, zero telemetry, 30+ lenguajes, 15+ agentes soportados con auto-detección, GitHub Action para CI, daemon multi-repo, y visualización en múltiples formatos. Para equipos que ya usan Claude Code, Codex o Cursor en repos medianos o grandes, CRG es el upgrade más directo para reducir costos y mejorar la calidad del contexto que recibe el agente.