Mantener actualizado el índice de CodeGraph

Objetivo

Al terminar sabrás cuándo CodeGraph mantiene tu índice al día de forma automática, cuándo tienes que hacerlo a mano y cómo revisar el estado del índice.

El índice es una copia de tu código. Cuando el código cambia y el índice no, tu agente confía en un mapa que ya no coincide con el territorio. Un índice desactualizado es peor que ninguno.

Prerrequisitos

CodeGraph instalado y un proyecto indexado con codegraph init (ver la guía de instalación).
Un agente de código conectado a CodeGraph mediante MCP.

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

Pasos

1. Entender la sincronización automática

Cuando tu agente lanza el servidor MCP de CodeGraph (codegraph serve --mcp), el servidor inicia un observador de archivos sobre el proyecto. Según la documentación oficial usa eventos nativos del sistema (FSEvents en macOS, inotify en Linux, ReadDirectoryChangesW en Windows):

Cuando cambian uno o dos archivos, sincroniza unos 300 ms después, y solo lo que cambió.
Las ráfagas de ediciones se agrupan en una sola sincronización (debounce por defecto: 2 segundos).
Si hay archivos pendientes de reindexar, las respuestas de la herramienta incluyen un aviso para que el agente lea esos archivos directamente.

El límite clave: el observador funciona solo mientras el servidor MCP está corriendo. Cuando cierras la sesión del agente, se detiene.

2. Saber cuándo debes sincronizar a mano

Haz una sincronización manual cuando hubo cambios mientras el observador no estaba corriendo:

Editaste código con el agente cerrado (en otro editor, por ejemplo).
Ejecutaste git pull, git checkout o git rebase y cambiaron muchos archivos.
El sistema operativo se quedó sin recursos para observar archivos. CodeGraph desactiva la sincronización automática una vez e imprime un mensaje que te indica correr codegraph sync.

3. Sincronizar manualmente

cd ruta/a/tu/proyecto
codegraph sync

Es una actualización incremental de lo que cambió desde el último índice. Es rápida. Su opción --quiet suprime la salida y está pensada para git hooks.

4. Revisar el índice

codegraph status

Muestra la cantidad de archivos, nodos y aristas, y avisa si el índice fue construido por una versión del motor más antigua que la que estás ejecutando.

5. Después de actualizar CodeGraph

codegraph upgrade --check   # ¿hay una versión más nueva?
codegraph upgrade           # instalarla
codegraph sync              # refresco incremental de tu índice

Los índices existentes siguen funcionando después de una actualización, pero fueron construidos por la versión anterior. codegraph sync es el refresco rápido. Si quieres que las mejoras de extracción de la nueva versión se apliquen en todo el índice, la salida del upgrade también sugiere codegraph index -f, una reconstrucción completa que tarda más.

Resultado esperado

Editas un archivo con tu agente abierto y el grafo se actualiza solo en pocos segundos.
Después de un git pull, codegraph sync deja el índice al día.
codegraph status no muestra advertencias de índice desactualizado.

Troubleshooting

Problemas comunes

El grafo no refleja tus ediciones: puede que el observador no esté corriendo (agente cerrado) o esté bloqueado (algunos entornos con sandbox, o un límite del sistema de observación de archivos agotado). Corre codegraph sync.
Ediciones hechas en un sistema de archivos distinto al que usa el agente (por ejemplo a través de una red o de una frontera de virtualización): puede que los eventos de archivo no lleguen. Corre codegraph sync a mano y, si es posible, edita y ejecuta el agente en el mismo entorno.
Demasiadas sincronizaciones mientras editas: sube el debounce con la variable de entorno CODEGRAPH_WATCH_DEBOUNCE_MS (entre 100 ms y 60 s).
Quieres desactivar la sincronización automática: define CODEGRAPH_NO_DAEMON=1. Tendrás que correr codegraph sync tú mismo.

Siguiente paso

Pon el índice a trabajar: hazle a tu agente preguntas estructurales sobre tu propio proyecto (qué llama a esto, qué se rompe si lo cambio) y observa cómo usa el grafo.