📊 CodeGraph — Grafo de Código Pre-indexado para Agentes IA

Grafo de conocimiento del código, local y auto-sincronizado

CodeGraph pre-indexa símbolos, llamadas y dependencias de un proyecto en un grafo SQLite, y se lo entrega a agentes como Claude Code, Cursor, Codex, OpenCode, Gemini, Antigravity, Kiro y Copilot mediante un único tool MCP: codegraph_explore.

• 💻 Repositorio: github.com/colbymchenry/codegraph
• 📚 Docs: colbymchenry.github.io/codegraph
• 🛠️ Stack: TypeScript + kernel nativo en Rust + SQLite (FTS5)
• 🧩 Licencia: MIT · ~74.6k ⭐ (al 2026-10-21)
• 🔒 100% local: sin API keys ni servicios externos

---

🎯 Qué es

Cuando un agente necesita entender código, normalmente descubre la estructura a la vieja usanza: grep, glob y leer archivos uno por uno, reconstruyendo llamadas y dependencias a mano. Eso son decenas de tool calls antes de empezar el trabajo real.

CodeGraph le entrega al agente el código exacto en una sola llamada: un grafo pre-construido con cada símbolo, arista de llamada y dependencia del código base. El agente pregunta una vez y recibe:

• El source literal de los símbolos relevantes, agrupado por archivo.
• Las rutas de llamada entre ellos, incluyendo saltos de despacho dinámico que grep no puede seguir.
• El blast radius: qué se rompe si cambias un símbolo.

La diferencia clave

No es un buscador de texto: es un índice semántico persistente. Mientras el agente edita, un watcher nativo (inotify en Linux) sincroniza el grafo en menos de un segundo. No hay sync manual ni índice obsoleto.

---

⚡ Por qué importa (benchmarks)

Medición sobre 7 repos open source en 7 lenguajes, con y sin CodeGraph, mediana de 4 corridas (Claude Opus 4.8, agosto 2026):

Métrica	Mejora
Tool calls	88% menos
Tiempo de respuesta	53% más rápido
Tokens	62% menos
Costo	44% más barato
Lecturas de archivos	0 en los 7 repos

Casos concretos:

Repo	Lenguaje	Tool calls	Velocidad
VS Code	TypeScript (~11k archivos)	2 vs 28	2.2×
Excalidraw	TypeScript (~640)	2 vs 43	3.6×
Tokio	Rust (~790)	3 vs 29	2.6×
Django	Python (~3k)	3 vs 14	1.35×

El otro lado de la moneda

La misma medición muestra que CodeGraph deja ~80% más contexto residual al final de una sesión multirretorno (en VS Code: 67k vs 18k tokens). Procesa menos tokens, pero ocupa más ventana. En sesiones largas con contexto chico, hay que presupuestarlo.

---

🚀 Instalación

Instalación en Linux / macOS

# 1. Instalar la CLI (no requiere Node)
curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh
 
# 2. Conectar con tus agentes (detecta OpenCode, Claude, Codex, etc.)
codegraph install
 
# 3. Indexar cada proyecto
cd mi-proyecto
codegraph init

Alternativas:

# Todo en uno con npx
npx @colbymchenry/codegraph
 
# Instalación npm (requiere Node)
npm i -g @colbymchenry/codegraph
 
# No interactivo
codegraph install --yes --init

Windows (PowerShell):

irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex

install ≠ indexar

codegraph install solo escribe la configuración MCP de cada agente. El índice se construye una vez por proyecto con codegraph init, que crea .codegraph/ y el grafo completo.

---

🔌 Integración con OpenCode

El instalador detecta OpenCode automáticamente y escribe la entrada MCP mcp.servers.codegraph con codemode: false, para que codegraph_explore quede en la lista nativa de tools. Si tenías la forma vieja (mcp.codegraph), codegraph install la migra.

Pasos:

1. codegraph install → elegir OpenCode.
2. Reiniciar OpenCode para que cargue el MCP.
3. codegraph init en el proyecto.
4. Verificar con codegraph status.
5. El agente empieza a usar CodeGraph solo cuando existe .codegraph/.

# Verificar que el índice existe y está sano
codegraph status

---

🧰 CLI esencial

Comando	Para qué
codegraph init [path]	Crear el índice del proyecto
codegraph index [path]	Reindexar completo (--force)
codegraph sync [path]	Actualización incremental manual
codegraph status [path]	Estadísticas y estado del índice
codegraph query <search>	Buscar símbolos por nombre (--kind, --limit, --json)
codegraph explore <query>	Source + rutas de llamada en una sola salida
codegraph node <symbol|file>	Source de un símbolo con callers, o archivo con líneas
codegraph callers <symbol>	Quién llama a una función
codegraph callees <symbol>	A qué llama una función
codegraph impact <symbol>	Qué se ve afectado si cambias ese símbolo (--depth)
codegraph affected <files...>	Tests afectados por cambios (ideal para CI/hooks)
codegraph files [path]	Estructura de archivos del proyecto
codegraph daemon	Gestionar daemons en segundo plano
codegraph uninit [path]	Quitar CodeGraph de un proyecto
codegraph uninstall	Quitar de todos los agentes + CLI (--keep-cli conserva la CLI)
codegraph upgrade	Actualizar a la última release
codegraph telemetry [on|off]	Ver o cambiar telemetría

Tests afectados en CI

#!/usr/bin/env bash
AFFECTED=$(git diff --name-only HEAD | codegraph affected --stdin --quiet)
if [ -n "$AFFECTED" ]; then
  npx vitest run $AFFECTED
fi

---

🤖 MCP Tools

El servidor MCP expone un solo tool por defecto:

Tool	Propósito
codegraph_explore	Responde casi cualquier pregunta en una llamada: source literal, rutas de llamada y blast radius. Acepta projectPath para consultar otro proyecto indexado.

Los demás (node, search, callers, callees, impact, files, status) siguen funcionando pero están ocultos para no saturar la lista de tools. Se reactivan con:

CODEGRAPH_MCP_TOOLS=explore,node,search,callers

---

🌐 Lenguajes soportados

20 lenguajes con kernel nativo en Rust, más el motor portable para el resto:

Grupo	Lenguajes
Web / Frontend	TypeScript, JavaScript, Svelte, Vue, Astro, Liquid
Backend	Python, Go, Rust, Java, C#, VB.NET, PHP, Ruby, Erlang, Scala, Kotlin
Sistemas	C, C++, Objective-C, Swift, CUDA, Metal, Nix
Datos / Infra	Terraform / OpenTofu, Solidity
Otros	ArkTS (HarmonyOS), Dart, Lua, Luau, R, Pascal / Delphi, CFML, COBOL

También reconoce rutas de frameworks (Django, Flask, FastAPI, Express, NestJS, Laravel, Rails, Spring, Gin, Axum, Astro, Next.js, Expo Router, React Router, TanStack Router, SvelteKit, Angular, Vue Router/Nuxt) y puentes Swift ↔ ObjC / React Native / Expo.

---

⚙️ Configuración

Zero-config por defecto. Ignora node_modules, vendor, dist, build, target, .venv, Pods, .next, lo que esté en .gitignore y archivos > 1 MB.

El único archivo opcional es codegraph.json en la raíz del proyecto:

{
  "exclude": ["static/", "**/vendor/**"],
  "include": ["Tools/", "Local/typescript/"],
  "deprioritize": ["scripts/", "optional-skills/"],
  "extensions": {
    ".dota_lua": "lua",
    ".tpl": "php"
  }
}

Clave	Efecto
exclude	Saca rutas del índice (incluso si están commiteadas)
include	Fuerza a indexar source que .gitignore esconde
deprioritize	Sigue indexado, pero pierde ranking frente al código real
extensions	Mapea extensiones no estándar a un lenguaje soportado

---

🔒 Privacidad y telemetría

• El índice vive en .codegraph/codegraph.db (SQLite + FTS5), en tu máquina.
• Sin API keys, sin servicios externos, sin enviar código.
• Telemetría anónima (solo tools/comandos usados y lenguajes indexados). Nunca código, rutas, nombres, queries ni IPs.

codegraph telemetry off
# o: CODEGRAPH_TELEMETRY=0 / DO_NOT_TRACK=1

---

⚠️ Limitaciones

• Contexto residual: respuestas densas que se quedan en la ventana (ver caveat arriba).
• Despacho dinámico: cubre callbacks, interfaces→impl y re-render de React, pero reflexión, DI containers y convenciones de framework tienen techo estático.
• Objective-C: soporte parcial (.mm ObjC++ puede parsear incompleto).
• WSL2 con proyectos en /mnt/c: locks y sockets poco confiables. Mover el proyecto a ext4 (~/) o usar CODEGRAPH_NO_DAEMON=1.
• Un solo writer por proyecto: no apuntar Windows y WSL al mismo .codegraph/; WSL usa .codegraph-wsl/.

---

🧯 Troubleshooting rápido

Síntoma	Solución
”CodeGraph not initialized”	codegraph init en la raíz del proyecto
Indexado lento	Revisar exclude / node_modules; usar --quiet
MCP no conecta	codegraph status + reiniciar el agente + codegraph install
Faltan símbolos	Esperar el auto-sync o codegraph sync; verificar lenguaje y .gitignore
database is locked	Actualizar a build ≥ 0.9; verificar Journal: wal; mover a disco local
Lock viejo	codegraph unlock [path]

---

🔗 Enlaces

• Context7 (docs actualizadas para agentes) — complemento: Context7 trae documentación de librerías; CodeGraph trae estructura del código propio.
• Github · Git
• Vault Ingest (cómo se guarda esta nota)