Instalar CodeGraph: guía básica

Objetivo

Al terminar tendrás CodeGraph instalado, conectado a tu agente de código mediante MCP, y tu primer proyecto indexado, de modo que el agente pueda responder preguntas estructurales ("¿quién llama a esto?", "¿qué se rompe si lo cambio?") desde un grafo en lugar de buscar a ciegas con grep.

CodeGraph es un grafo de conocimiento de código local. Analiza tu repositorio, guarda los símbolos y sus relaciones en una base SQLite dentro del proyecto (.codegraph/) y los expone a los agentes mediante un servidor MCP y una CLI. Todo corre en tu máquina.

Prerrequisitos

macOS, Linux o Windows.
Node.js (una versión LTS reciente) y npm. El proyecto también documenta scripts de instalación para máquinas sin Node; revisa la documentación oficial.
Un agente de código con soporte MCP. Esta guía usa Claude Code. codegraph install también lista como destinos Cursor, Codex CLI, opencode, Gemini CLI, Antigravity IDE, Kiro, GitHub Copilot y Hermes Agent.
Un proyecto local (idealmente un repositorio git) para indexar.

Esta guía cubre CodeGraph v1.6 al estado de octubre de 2026.

Pasos

1. Instalar la CLI

npm install -g @colbymchenry/codegraph

Abre una terminal nueva después, para que el comando codegraph se resuelva.

2. Verificar la instalación

codegraph --version

Verificación esperada: imprime un número de versión.

3. Conectarlo a tu agente

codegraph install

Te pregunta qué agentes configurar y si instalar de forma global o local. Para una instalación sin preguntas:

codegraph install --yes          # detecta los agentes e instala de forma global
codegraph install --yes --init   # igual, y además indexa el proyecto actual

Para Claude Code, el instalador también pregunta si quieres anticipar CodeGraph en los prompts de tipo "how / where / trace". Esto agrega un hook: cuando haces una pregunta estructural, CodeGraph inyecta de entrada el código fuente y las rutas de llamadas relevantes en el prompt, así el agente necesita menos pasos. Agrega un instante de latencia a esos prompts. Responder que sí es un buen valor por defecto; puedes apagarlo después (ver Troubleshooting).

4. Indexar tu proyecto

Desde la raíz del repositorio:

cd ruta/a/tu/proyecto
codegraph init

Esto crea el directorio .codegraph/ y construye el índice inicial. En repos grandes el índice puede pesar bastante, así que agrega .codegraph/ a tu .gitignore: cada persona indexa su propia copia.

5. Revisar el índice

codegraph status

Verificación esperada: conteos distintos de cero de archivos, nodos y aristas, más un desglose de nodos por tipo (funciones, métodos, clases, rutas...).

6. Probar una consulta desde la CLI

codegraph explore "login authentication"
codegraph callers authenticate
codegraph impact authenticate

CodeGraph no tiene IA por dentro: busca por palabras clave contra nombres de símbolos, firmas y docstrings, y luego recorre el grafo. Usa términos que realmente aparezcan en tu código (normalmente en inglés). Una consulta como "how does login work" funciona porque login está en el código; "inicio de sesión" no coincidiría con una función login.

7. Hacerle una pregunta estructural a tu agente

Abre tu agente en el proyecto y pregunta algo como "¿cómo funcionan las reservas?". El agente debería llamar a CodeGraph (codegraph_explore) y responder con código fuente, rutas de llamadas y un resumen del radio de impacto en un solo paso. El agente es quien traduce tu lenguaje natural a buenas palabras clave.

Resultado esperado

codegraph --version imprime una versión.
codegraph status muestra un índice poblado para tu proyecto.
codegraph explore "<palabras clave>" devuelve símbolos, código y rutas de llamadas.
Tu agente usa CodeGraph cuando haces preguntas estructurales.

Troubleshooting

Problemas comunes

codegraph: command not found: abre una terminal nueva para que se cargue el PATH actualizado.
npm ls -g muestra una versión más vieja que codegraph --version: codegraph upgrade descarga su propio binario y no actualiza lo que npm registra. Confía en codegraph --version.
codegraph status muestra ceros o el proyecto no está inicializado: corre codegraph init desde la raíz del repositorio.
La consulta no encuentra nada: usa palabras clave que existan en el código, normalmente en inglés. La herramienta no entiende lenguaje natural por sí sola.
El agente ignora CodeGraph: confirma que el servidor MCP se instaló para ese agente (codegraph install) y reinicia la sesión del agente.
Los prompts se sienten lentos o el hook da error (reportado en Windows con Git Bash): desactiva solo el hook de anticipación con CODEGRAPH_NO_PROMPT_HOOK=1 en el bloque env de ~/.claude/settings.json. La herramienta MCP y la CLI siguen funcionando.
Actualizar más adelante: codegraph upgrade --check indica si hay una versión nueva; codegraph upgrade la instala. Después refresca tus índices con codegraph sync.

Siguiente paso

Aprende a mantener el índice al día cuando tu código cambia.