CubeLabs

1. ¿Qué es CodeGraph y por qué tu agente lo necesita?

CodeGraph es un knowledge graph local de tu código: una base de datos SQLite (`.codegraph/codegraph.db`) que contiene cada símbolo — funciones, clases, métodos — y cada relación entre ellos — llamadas, imports, herencias, implementaciones — extraída con un kernel nativo en Rust. Cuando tu agente pregunta "¿cómo llega una petición a la base de datos?", en vez de hacer 28 llamadas de descubrimiento (find, ls, grep, read), hace una: `codegraph_explore`, y recibe el código fuente verbatim agrupado por archivo, los call paths entre símbolos y el resumen del blast radius.

El problema que resuelve es el bucle grep-and-read: los agentes actuales gastan la mayor parte de su presupuesto en descubrir estructura antes de hacer el trabajo real. CodeGraph pre-indexa esa estructura, así el agente responde directamente desde el grafo.

Los benchmarks usan 7 codebases reales (VS Code ~11k archivos, Excalidraw, Django, Tokio, OkHttp, Gin, Alamofire) con Claude Code headless y el CLI bloqueado en ambos brazos para evitar contaminación. CodeGraph ganó en todos los repos, desde 110 hasta 11.000 archivos.

2. Instalación en 1 minuto

CodeGraph se instala como un único binario autocontenido — no necesitas Node.js ni compilar nada: cada release incluye su propio runtime. Tres vías equivalentes:

# Opción A: instalador oficial (macOS / Linux) — no requiere Node
curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh

# Opción B: Windows (PowerShell)
irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex

# Opción C: npm (si ya tienes Node, funciona en cualquier versión)
npm i -g @colbymchenry/codegraph

# Verifica
codegraph --version

El instalador coloca `codegraph` en tu PATH pero no cambia tu shell actual — abre una terminal nueva antes del siguiente paso para que el comando se resuelva.

¿Instalaste por curiosidad y quieres revertirlo? codegraph uninstall elimina la configuración de todos los agentes que tocó y el CLI mismo, mostrándote antes todo lo que va a borrar. Con --keep-cli solo quita las configuraciones de agentes. Los índices de proyectos (`.codegraph/`) no se tocan; se eliminan por proyecto con codegraph uninit.

3. Conecta tus agentes: codegraph install

Instalar el CLI no conecta nada: el paso clave es cablear el servidor MCP de CodeGraph dentro de tus agentes. En una terminal nueva:

codegraph install

El instalador interactivo:

• Detecta automáticamente los agentes instalados: Claude Code, Cursor, Codex CLI, opencode, Hermes Agent, Gemini CLI, Antigravity IDE, Kiro y GitHub Copilot (VS Code, Copilot CLI y JetBrains).
• Pregunta si quieres instalar `codegraph` en el PATH (necesario para que los agentes lancen el servidor MCP).
• Pregunta si la config aplica a todos tus proyectos o solo a este.
• Escribe la config MCP de cada agente + una sección marcada con markers en el archivo de instrucciones del agente (CLAUDE.md / AGENTS.md / GEMINI.md) — así los subagentes y agentes sin MCP aprenden el comando `codegraph explore`.
• Configura auto-allow cuando Claude Code es uno de los targets.

Para scripting y CI existe el modo no interactivo:

codegraph install --yes                              # auto-detecta agentes, instalación global
codegraph install --yes --init                       # lo mismo + indexa el proyecto actual (bootstrap one-shot)
codegraph install --target=cursor,claude --yes       # lista de targets explícita
codegraph install --target=auto --location=local     # agentes detectados, configuración local al proyecto
codegraph install --print-config codex               # imprime el snippet sin escribir nada

Importante: reinicia tu agente (Claude Code, Cursor, Codex, VS Code, etc.) después de instalar para que el servidor MCP cargue.

4. Indexa tu primer proyecto: codegraph init

Entra en tu proyecto y construye el grafo. Un solo comando crea el directorio local y construye el grafo completo en el mismo paso:

cd /ruta/a/tu/proyecto
codegraph init

Esto crea .codegraph/ con la base SQLite. El tiempo varía desde segundos (proyectos pequeños) hasta un par de minutos (proyectos grandes). En una workstation, el repo del compilador Swift (27k archivos) indexa fresco en ~100 segundos; en un VPS de 2 cores / 6GB, el kernel de Linux (70k archivos, 2M símbolos, 6.4M relaciones) completa en menos de 12 minutos con el pipeline auto-ajustado.

Lo mejor de todo: no hay que sincronizar nada. El auto-sync está activado por defecto — CodeGraph observa el proyecto y actualiza el grafo con cada cambio de archivo, mientras tu agente edita código o tú añades/borras archivos. El índice nunca está obsoleto y no hay nada que re-ejecutar.

¿No quieres el grafo en un proyecto? codegraph uninit lo elimina (con --force salta la confirmación).

5. Arquitectura: el kernel Rust y el ciclo de vida del grafo

Entender cómo funciona por dentro te ayuda a sacarle partido. CodeGraph tiene un kernel nativo en Rust que parsea el código con gramáticas tree-sitter compiladas dentro: 20 lenguajes — TypeScript, JavaScript, Java, Python, Go, C, C++, Rust, C#, Ruby, PHP, Swift, Kotlin, Scala, Dart, R, Lua, Luau, etc. — con una sola frontera de cruce por archivo. Cada lenguaje se publica solo tras demostrar grafos byte-for-byte idénticos al motor de referencia sobre repos reales, desde librerías pequeñas hasta el kernel de Linux.

El ciclo de vida del grafo tiene 4 fases:

El pipeline se escala solo a la máquina: worker pools, resolución paralela y cachés de análisis se dimensionan con los cores reales (consciente de contenedores: un VPS con 2 cores se dimensiona para 2, no para los 64 del host), la RAM medida de verdad y el coste medido de tu proyecto. Un workstation recibe el pipeline paralelo completo; un VPS de 2 cores recibe uno afinado para terminar.

6. Explora el grafo: query, explore, node y files

La CLI es tu interfaz directa con el grafo, y cada comando tiene su equivalente en las herramientas MCP:

codegraph query "sendEmail"                  # busca símbolos por nombre (--kind, --limit, --json)
codegraph explore "authentication flow"       # una llamada: fuente verbatim + call paths + blast radius
codegraph node "UserService"                  # fuente de un símbolo + sus callers, o lee un archivo con números de línea
codegraph files                               # muestra la estructura de archivos (--format, --filter, --max-depth)
codegraph search "interface:Repository"       # búsqueda por tipo de entidad

codegraph explore es la joya: responde casi cualquier pregunta en una llamada — "¿cómo funciona X?", un flujo ("¿cómo llega X a Y?") o un reconocimiento de zona — devolviendo el fuente verbatim de los símbolos relevantes agrupado por archivo, los call paths entre ellos incluyendo saltos de dynamic dispatch (callbacks, re-renders de React, interface→impl) que grep no puede seguir, y un resumen del blast radius. Si nombras un archivo o símbolo en la query, lees su fuente actual con números de línea — la misma forma que la herramienta Read.

Ejemplos de búsquedas útiles:

• codegraph query "UserService" — encuentra la definición y sus usos.
• codegraph explore "how does a request reach the database" — flujo completo con los call paths.
• codegraph files --filter "src/auth" --max-depth 2 — estructura de un área concreta.
• codegraph node "authenticate" — el cuerpo de la función con sus callers.

7. Callers, callees e impacto: blast radius antes de tocar nada

Antes de modificar una función, necesitas saber quién la llama, a quién llama y qué se rompería. CodeGraph responde esto en milisegundos con tres comandos:

codegraph callers "UserService.getUser"       # qué llama a este método (--limit, --json)
codegraph callees "UserService.getUser"       # qué llama este método (--limit, --json)
codegraph impact "UserService"                # qué código se ve afectado al cambiar el símbolo (--depth, --json)

codegraph impact es el análisis de blast radius: recorre transitivamente los callers del símbolo hasta la profundidad que indiques (--depth 2 para saltos indirectos) y te devuelve el conjunto de código afectado. Perfecto para:

• Refactorización: encuentra todas las referencias a una clase o interfaz antes de renombrarla.
• Code review: revisa dependencias de una función antes de aprobar un cambio.
• Onboarding: genera contexto de un proyecto nuevo para un agente que nunca lo ha visto.

8. codegraph affected: tests en CI

Una de las funciones más infravaloradas: codegraph affected traza las dependencias de import de forma transitiva para encontrar qué archivos de test se ven afectados por los archivos fuente que cambiaste.

codegraph affected src/utils.ts src/api.ts              # pasa archivos como argumentos
git diff --name-only | codegraph affected --stdin        # pipe desde git diff
codegraph affected src/auth.ts --filter "e2e/*"          # patrón de test personalizado

Ejemplo de hook de CI que ejecuta solo los tests afectados:

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

Con esto, un PR que toca src/utils.ts ejecuta únicamente los tests que dependen transitivamente de ese archivo — en vez de la suite completa. Menos tiempo de CI, feedback más rápido.

9. CodeGraph como servidor MCP

Cuando CodeGraph corre como servidor MCP expone una única herramienta: codegraph_explore. La decisión de diseño es deliberada: la medición de comportamiento con agentes reales mostró que una herramienta fuerte orienta mejor que un menú de herramientas estrechas — menos elecciones erróneas y ahorro de contexto en cada sesión.

Las demás herramientas (codegraph_node, codegraph_search, codegraph_callers, codegraph_callees, codegraph_impact, codegraph_files, codegraph_status) siguen funcionando pero no aparecen listadas por defecto — todo lo que devuelven ya llega inline en codegraph_explore (sección blast radius, mapa de relaciones, el cuerpo de un símbolo como lista de callees).

Para re-habilitarlas en la superficie MCP, usa la variable de entorno CODEGRAPH_MCP_TOOLS:

CODEGRAPH_MCP_TOOLS=explore,node,search,callers

Si prefieres configurar a mano (sin instalador), así se ve la integración en ~/.claude.json:

{
  "mcpServers": {
    "codegraph": {
      "type": "stdio",
      "command": "codegraph",
      "args": ["serve", "--mcp"]
    }
  }
}

Y para auto-aprobar todas las herramientas de CodeGraph en Claude Code (opcional, en ~/.claude/settings.json):

{
  "permissions": {
    "allow": [
      "mcp__codegraph__*"
    ]
  }
}

10. Configuración avanzada, librería y buenas prácticas

Configuración casi cero. CodeGraph es zero-config por defecto: el soporte de lenguajes es automático por extensión y no hay nada que cablear por lenguaje. Excluye por defecto directorios de dependencias/build/caché (node_modules, vendor, dist, build, target, .venv, Pods, .next), respeta tu .gitignore y salta archivos de más de 1 MB.

El archivo opcional codegraph.json en la raíz del proyecto afina el comportamiento:

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

• exclude — patrones gitignore-style para sacar del índice algo que está commiteado (p.ej. un theme vendored).
• include — fuerza a incluir fuente real que está gitignored a propósito (proyectos con segundo VCS). Un exclude explícito siempre gana; los skips integrados (node_modules, dist, .git) nunca se re-incluyen.
• deprioritize — rutas que se quedan indexadas y buscables pero dejan de ganar contra tu código de primera clase en el ranking (ideal para árboles scripts/ con nombres genéricos como usage o status).
• extensions — mapea extensiones no estándar a un lenguaje soportado. Re-indexa con codegraph index tras cambiar el mapeo.

Uso como librería. El paquete npm re-exporta la API programática — puedes incrustar el grafo en tu propia app (p.ej. un proceso principal de Electron):

import CodeGraph from '@colbymchenry/codegraph';

const cg = await CodeGraph.init('/path/to/project');

await cg.indexAll({
  onProgress: (p) => console.log(`${p.phase}: ${p.current}/${p.total}`)
});

const results = cg.searchNodes('UserService');
const callers = cg.getCallers(results[0].node.id);
const context = await cg.buildContext('fix login bug', {
  maxNodes: 20, includeCode: true, format: 'markdown'
});
const impact = cg.getImpactRadius(results[0].node.id, 2);

cg.watch();    // auto-sync en cambios
cg.unwatch();  // deja de observar
cg.close();

Requisitos para incrustarlo: npm (npm i @colbymchenry/codegraph), Node 22.5+ para el node:sqlite integrado (el CLI y el servidor MCP no se ven afectados — corren en su runtime autocontenido), y skipLibCheck: true en TypeScript.

Buenas prácticas resumidas:

1. Instala una vez, cablea todos tus agentes (codegraph install --yes), indexa cada proyecto (codegraph init).
2. Deja que el auto-sync haga su trabajo — no corras codegraph sync a mano.
3. En prompts largos con ventana pequeña, presupuesta el footprint: CodeGraph deja ~80% más contexto residual residente al final de la sesión (mecanismo del mismo que lo hace rápido: un payload denso que responde y se queda, frente a muchos resultados pequeños que se evictan).
4. Usa codegraph affected en CI para testear solo lo afectado.
5. Revisa la nota de staleness tras ediciones: si el agente muestra el banner, el índice se re-sincroniza solo en ~2 segundos.