davidw-philips/cgraph

CodeGraph (codegraph)

codegraph construye y mantiene un grafo de conocimiento local (SQLite) que se sincroniza automáticamente con cada símbolo, borde de llamada y dependencia en un código base. Una vez inicializado, tu agente responde preguntas estructurales directamente desde el grafo a través de la herramienta MCP codegraph_explore — en una sola llamada, con cero lecturas de archivos, en lugar de un bucle de grep/lectura.

Cuándo Usarlo

• Responder "¿Cómo funciona X?", "¿Cómo llega X a Y?" o inspeccionar un área desconocida del repositorio activo.
• Encontrar llamantes/llamados de una función, trazar rutas de llamadas o delimitar el radio de explosión de un cambio.
• Iniciar, gestionar o detener los demonios de fondo y procesos de entorno de CodeGraph.
• Navegar y mantener índices de grafos a través de ramas de Git, rebases y worktrees de Git.
• Cualquier pregunta que de otro modo responderías buscando con grep o leyendo varios archivos para reconstruir la estructura manualmente.

NO lo uses para un repositorio que aún no tenga un índice .codegraph/ (ejecuta codegraph init primero) ni para repositorios externos/públicos que no hayas indexado localmente — prefiere la habilidad deepwiki para esos.

Verificación Previa

command -v codegraph || Get-Command codegraph

Si falta, consulta INSTALL.md, o instala directamente con:

# macOS / Linux — no requiere Node.js, incluye su propio runtime
curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh

# Windows (PowerShell) — no requiere Node.js
irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex

Esto es todo lo que la mayoría de los entornos necesitan — pasa directamente a Flujo de Trabajo e Inicio a continuación. Solo usa los scripts/ incluidos (consulta INSTALL.md) si necesitas específicamente la ruta de instalación npm o la API de la biblioteca Node de CodeGraph.

Flujo de Trabajo e Inicio

1. Configuración Única por Máquina

Conecta CodeGraph con este agente (confirma antes de cambiar algo):

codegraph install

2. Configuración Inicial por Proyecto

Construye el grafo para el proyecto activo (crea .codegraph/codegraph.db; ejecuta el índice inicial completo):

cd tu-proyecto
codegraph init

3. Inicio Diario (Al Empezar a Trabajar)

No es necesario iniciar manualmente un demonio o servicio en segundo plano antes de trabajar:

• Sesiones de Agente (MCP): Tu anfitrión de IA (VS Code Copilot, Claude Code, etc.) inicia el servidor MCP automáticamente a través de codegraph serve --mcp. El servidor se conecta o genera un demonio en segundo plano bajo demanda, completo con un vigilante del sistema de archivos del SO.
• Verificar Estado: Ejecuta codegraph status para verificar la salud del índice, conteos de símbolos/aristas y elementos pendientes de sincronización.
• Sincronización de Puesta al Día: Si los archivos cambiaron mientras el agente estaba cerrado (por ejemplo, commits extraídos), ejecuta codegraph sync para una actualización incremental rápida e inmediata.

4. Consultar la Estructura

Tu agente llama a la herramienta MCP codegraph_explore automáticamente una vez conectado. La misma capacidad está disponible desde un shell:

codegraph explore "cómo llega X a Y"
codegraph callers algunaFuncion
codegraph callees algunaFuncion
codegraph impact algunSimbolo

Ciclo de Vida del Entorno y el Demonio

CodeGraph ejecuta un demonio en segundo plano (modo demonio) por defecto para que múltiples sesiones de cliente compartan un único vigilante, caché y manejo de SQLite.

Apagar Demonios

• Detención Interactiva: Ejecuta codegraph daemon (o codegraph daemons). Selecciona el demonio del proyecto (flota al inicio) o elige detener todos los demonios.
• Detención Scripteada / No Interactiva: Los demonios registran su PID en <raíz_proyecto>/.codegraph/daemon.pid. Termina ese ID de proceso directamente (o inspecciona ~/.codegraph/daemons/<hash>.json).
• Limpiar Bloqueos Obsoletos: Si un proceso falla o se termina abruptamente, limpia los bloqueos obsoletos y artefactos de demonios huérfanos con:

  codegraph unlock
  

Alternativas de Entorno (Demonio y Vigilante)

• Modo Directo (Sin Demonio): Establece CODEGRAPH_NO_DAEMON=1 para forzar que cada sesión MCP y CLI se ejecute como un proceso independiente y autocontenido en lugar de conectarse a un demonio compartido.
• Deshabilitar el Vigilante de Archivos: Establece CODEGRAPH_NO_WATCH=1 (o usa la bandera --no-watch) para deshabilitar el vigilante del sistema de archivos en vivo. Recomendado en sistemas de archivos lentos (unidades WSL2 /mnt/, montajes de red) o configuraciones con limitaciones de batería.

Desmantelamiento / Desinicialización

• Eliminar del Proyecto: Ejecuta codegraph uninit para eliminar el índice .codegraph/ y los ganchos de sincronización de Git (--force omite la confirmación).
• Eliminar de la Máquina: Ejecuta codegraph uninstall (o codegraph uninstall --keep-cli para mantener el binario CLI).

Trabajar con Ramas de Git y Worktrees

Cambio de Rama de Git (Árbol de Trabajo Único)

• Sincronización Basada en Sistema de Archivos: CodeGraph rastrea rutas de archivos y hashes de contenido en SQLite, no git status. Cambiar de rama (git switch <rama> o git checkout <rama>) modifica archivos en disco; el vigilante de archivos detecta automáticamente los cambios y sincroniza el índice de forma incremental en aproximadamente 2 segundos.
• Sincronización Manual: Si el vigilante estuvo deshabilitado o inactivo durante el cambio, ejecuta codegraph sync para una puesta al día incremental rápida.
• Rebases / Reconstrucciones Mayores: Después de un rebase masivo o fusión de ramas con conflictos intensos, fuerza una reconstrucción limpia del índice con:

  codegraph index --force
  

• Ganchos de Sincronización de Git (Cuando el Vigilante Está Apagado): Si CODEGRAPH_NO_WATCH=1 está establecido, CodeGraph puede instalar ganchos post-commit, post-merge y post-checkout que invocan codegraph sync en segundo plano automáticamente después de cambios de rama.

Worktrees de Git y el Peligro del "Índice Prestado"

• Detección de Índice: CodeGraph descubre .codegraph/ recorriendo los directorios padre desde el directorio de trabajo actual.
• El Peligro: Al usar worktrees de Git (por ejemplo, git worktree add ../feature-worktree feature), si el worktree carece de su propio directorio .codegraph/, CodeGraph sube y se vincula al índice .codegraph/ del checkout principal. ¡Las consultas en el worktree devolverán símbolos y fuentes de la rama del checkout principal, perdiendo los cambios específicos del worktree!
• Detección de Desajuste: CodeGraph verifica detectWorktreeIndexMismatch comparando git rev-parse --show-toplevel contra indexRoot mediante git rev-parse --git-common-dir. Cuando un worktree toma prestado el índice principal, CodeGraph emite advertencias en codegraph status y las herramientas de consulta MCP.
• La Regla de Oro para Worktrees: Ejecuta siempre codegraph init (o codegraph init -i) dentro de cada directorio de worktree. Cada worktree debe tener su propio directorio .codegraph/ dedicado para indexar su rama de forma independiente.
• Aislamiento de Directorio Personalizado: Establece CODEGRAPH_DIR (por ejemplo, export CODEGRAPH_DIR=.codegraph-worktree) si se requiere un nombre de carpeta de índice personalizado o aislamiento (por ejemplo, separar checkouts de Windows y WSL2).

Reglas

• Confía en los resultados del grafo: se mantiene sincronizado mediante un vigilante de archivos (antirrebote de 2 segundos después de un guardado); no lo verifiques de nuevo con grep.
• Trata el código fuente devuelto por codegraph_explore como ya leído; no vuelvas a abrir el mismo archivo con la herramienta Read.
• Consulta solo un proyecto que tenga un índice .codegraph/. Una ruta sin él dará una guía clara para usar herramientas integradas en su lugar: la indexación sigue siendo una decisión deliberada, no automática.
• En worktrees de Git, verifica con codegraph status que el worktree tenga su propio índice local en lugar de tomar prestado el índice del árbol principal.
• Prefiere codegraph_explore (o codegraph explore desde la CLI) sobre las herramientas ocultas más específicas (codegraph_node, codegraph_search, codegraph_callers, codegraph_callees, codegraph_impact, codegraph_files, codegraph_status) — todo lo que devuelven ya llega en línea con codegraph_explore.

Consulta INSTALL.md para opciones de instalación, incluidos los scripts de verificación/instalación de Node.js incluidos en scripts/, necesarios solo para la ruta de instalación npm o la integración de bibliotecas.