CodeGraph: un índice local de código para agentes

Todo lo que hay que saber sobre colbymchenry/codegraph: una herramienta local que convierte un repositorio en un grafo consultable mediante CLI, biblioteca y MCP para agentes de programación.

Qué es CodeGraph

CodeGraph crea un grafo de conocimiento preindexado de un repositorio: símbolos, archivos, llamadas, importaciones, herencia y otras relaciones. Lo almacena localmente en SQLite con búsqueda FTS5 y lo expone al agente mediante un servidor MCP, además de una interfaz de línea de comandos y una API de Node.js. Según el README y la documentación oficial, su propósito es que un agente recupere contexto estructural y el alcance de un cambio sin reconstruir la arquitectura con muchas búsquedas y lecturas de archivos.

La herramienta declara soporte para Claude Code, Codex CLI, Cursor, OpenCode, Hermes Agent, Gemini CLI, Antigravity y Kiro. También declara que no necesita claves de API y que el grafo queda en la máquina. Esto es una propiedad del producto documentada por su autor, no una auditoría independiente de privacidad.

El origen: un proyecto individual de 2026

La API de GitHub fecha la creación del repositorio el 18 de enero de 2026. Su autor y principal contribuidor es Colby Mchenry (colbymchenry): su perfil de GitHub se describe como profesional con más de quince años construyendo software. El paquete de npm apareció el mismo día, según su historial de publicación.

La tensión que plantea el proyecto es concreta: un agente que debe entender una base de código suele usar búsqueda textual y lectura de archivos para inferir rutas de llamada y dependencias. CodeGraph propone invertir ese orden: construir el índice antes de la consulta, mantenerlo sincronizado y devolver al agente un conjunto de símbolos, código y relaciones pertinentes. El README reconoce un límite importante: sus cifras de menos tokens y menor coste miden procesamiento y llamadas, pero sus respuestas densas pueden dejar más contexto residente en sesiones largas.

Filosofía y principios

Local primero: la base .codegraph/codegraph.db y el índice residen en el proyecto; el README declara que no envía código ni consultas a un servicio externo.

Representación de un servidor local blindado dentro de una cúpula protectora, sin conexiones externas, que simboliza el enfoque local primero.

Contexto estructural antes que exploración manual: una consulta puede entregar código, rutas de llamadas y radio de impacto, en vez de delegar la reconstrucción de la estructura al agente.
Actualización incremental: el servidor MCP observa cambios del sistema operativo y sincroniza el índice por archivo tras una ventana de espera.

Visualización de un pulso de actualización incremental recorriendo el grafo de código tras detectarse un cambio, con un temporizador de espera en segundo plano.

Un punto de entrada para el agente: el README deja codegraph_explore como herramienta MCP visible por defecto; las herramientas más estrechas siguen disponibles, pero se pueden habilitar explícitamente.

Un agente de IA analizando una ruta de llamada entre dos funciones sobre una proyección tridimensional del grafo de código.

Distribución verificable: desde julio de 2026 el proyecto documenta procedencia de npm y atestaciones firmadas para los archivos de las publicaciones de GitHub.

Cómo funciona

El flujo técnico documentado tiene cuatro fases:

Un núcleo nativo en Rust analiza una parte de los lenguajes con gramáticas de Tree-sitter; las rutas portátiles y los archivos que no puedan usar el binario precompilado recurren al motor alternativo.
La extracción guarda nodos y aristas en .codegraph/codegraph.db, una base SQLite con FTS5.

Núcleo SQLite luminoso en el centro de una arquitectura de grafo, rodeado de tablas de nodos, aristas y el índice de búsqueda FTS5.

El resolvedor conecta llamadas con definiciones, importaciones con archivos, herencia y patrones de marcos web; el README enumera rutas para, entre otros, Django, FastAPI, Express, NestJS, Rails, Spring, Laravel y varios marcos de Go y Rust.
Al ejecutar el servidor MCP, un observador de archivos sincroniza cambios. La documentación indica una espera predeterminada de dos segundos, configurable mediante CODEGRAPH_WATCH_DEBOUNCE_MS; durante ese intervalo la respuesta puede advertir que un archivo pendiente debe leerse directamente.

La versión v1.5.0, publicada el 21 de julio de 2026, incorporó el núcleo Rust para veinte lenguajes y ajustes adaptativos de trabajadores y memoria. Sus notas afirman sincronización inferior a un segundo en repositorios de prueba, pero son mediciones del propio proyecto.

Estado oficial y semioficial

No se recuperó evidencia de una inclusión en un mercado oficial de Claude, OpenAI, Cursor u otro proveedor. La integración es semioficial en el sentido técnico, no comercial: codegraph install detecta configuraciones de los agentes compatibles y registra el servidor MCP en ellas. Ello no equivale a certificación, respaldo ni soporte por parte de esos proveedores.

El paquete sí está publicado en el registro oficial de npm como @colbymchenry/codegraph. La documentación enlaza también un repositorio de Homebrew del mismo autor, colbymchenry/homebrew-codegraph, pero no se recuperó una fórmula oficial de Homebrew ni debe inferirse su disponibilidad en el catálogo principal.

El ecosistema

Repositorios del autor y componentes relacionados

colbymchenry/homebrew-codegraph (0 estrellas en la consulta): repositorio que se describe como repositorio de Homebrew para CodeGraph.
colbymchenry/shopify-graphql-admin-mcp (22 estrellas): otro servidor MCP del autor, para conectar Claude con una tienda Shopify. Es un proyecto hermano, no una dependencia de CodeGraph.
colbymchenry/frontend-audit-skill (19 estrellas): habilidad de auditoría visual con regresión; tampoco es un componente confirmado de CodeGraph.
El propio repositorio contiene codegraph-kernel, telemetry-dashboard y telemetry-worker. Son directorios del monorrepositorio, no repositorios públicos independientes.

Bifurcaciones, puertos y extensiones

La API de bifurcaciones muestra derivados con cambios explícitos, frente a muchos espejos que conservan la descripción original:

Un holograma central de CodeGraph rodeado de nodos satélite que representan bifurcaciones y puertos de la comunidad, incluidos derivados en Rust y Hermes Agent.

Cleboost/codegraph-rs (42 estrellas) se describe como una implementación en Rust de bajo coste general.
ingeniousfrog/CodeDelta (26 estrellas) declara visualizar cambios estructurales y rastrear orígenes de incidencias entre commits.
nanofatdog/codegraph_hermes (9 estrellas) conserva el enfoque de grafo local y menciona Hermes Agent.
IppearPeng/codegraphFD (2 estrellas) declara añadir soporte para Fortran.
zybk1003/codegraph (1 estrella) conserva una descripción traducida al chino; es una bifurcación comunitaria, no una traducción oficial verificada.

Además, la búsqueda de GitHub recuperó proyectos de la misma categoría, aunque no dependencias: CodeGraphContext/CodeGraphContext (4.054 estrellas) y Jakedismo/codegraph-rust (860 estrellas). La búsqueda no estableció relaciones de afiliación con colbymchenry/codegraph.

Números del repositorio

Medición: 6 de agosto de 2026, API de GitHub y API de npm.

Métrica	Valor
Estrellas	64.908
Bifurcaciones	4.078
Suscriptores reales	147
Commits	825
Incidencias abiertas indicadas por la API	393
Lenguaje principal indicado por GitHub	C
Licencia	MIT
Creación	18 de enero de 2026
Última actualización de metadatos	6 de agosto de 2026
Última publicación	`v1.5.0`, 21 de julio de 2026
Descargas de npm, últimos 7 días disponibles	75.949
Descargas de npm, últimos 30 días disponibles	336.711

Los contribuidores principales devueltos por la API fueron colbymchenry (731 contribuciones), github-actions[bot] (26), omonien (16), andreinknv (7) y MO2k4 (4). El conteo de 825 commits procede de la última página del enlace de paginación de la API. open_issues_count puede incluir solicitudes de cambios abiertas. El campo watchers_count de la respuesta general replica el número de estrellas; por ello se informa subscribers_count como suscriptores reales.

Cómo contribuir

No existe CONTRIBUTING.md ni plantilla de solicitud de cambios en las rutas públicas consultadas. Sí hay pruebas (__tests__), configuración de Vitest y flujos de GitHub, pero las fuentes recuperadas no documentan un flujo de contribución, una rama objetivo ni requisitos de revisión. Por tanto, no se debe inventar un proceso: antes de aportar cambios conviene abrir una incidencia o consultar el repositorio para conocer el criterio vigente.

Cómo lo recibió la comunidad

La evidencia externa recuperable es limitada y debe separarse de las afirmaciones del proyecto:

El envío directo de Hacker News 49054696, titulado con el nombre del proyecto y enviado por handfuloflight el 26 de julio de 2026, tenía 5 puntos y 0 comentarios. Acredita difusión, no una reseña ni entusiasmo comunitario.
En el hilo 48994388, con 2 puntos y 1 comentario, el usuario pankaj4u4m, mantenedor declarado de LemonCrow, publicó una comparación. Afirmó que en sus 35 ejecuciones CodeGraph redujo el coste total un 16,3 %, menos que la reducción de tokens que discutía. También afirmó un valor MRR inferior al de su producto. El propio autor del comentario advierte que no es una reseña independiente y dice haber pedido revisión de configuraciones; por ello son resultados atribuidos, no un benchmark confirmado.
El README publica un benchmark propio re-medido el 5 de agosto de 2026 en siete repositorios y afirma 88 % menos llamadas, 53 % menos tiempo, 62 % menos tokens y 44 % menos coste en la mediana. Su metodología y los repositorios están descritos en el README, pero no se recuperó una réplica externa; deben leerse como resultados del proyecto.

Dos gráficos de barras comparando un agente estándar frente a un agente con CodeGraph en llamadas, tiempo y coste, con el agente CodeGraph mostrando valores mucho más bajos.

Las búsquedas de Reddit en los subreddits solicitados no devolvieron contenido recuperable por la protección automatizada del sitio. Las consultas de X, Product Hunt y YouTube tampoco aportaron una publicación, página de lanzamiento o vídeo verificable de este proyecto. DEV Community mostró una página de búsqueda, sin artículo identificable sobre el repositorio. No se recuperó una mención verificable en newsletters o pódcast ni una inclusión verificable en una lista awesome-*.

CodeGraph frente a otras propuestas

Propuesta	Coincidencia verificable	Diferencia verificable
`CodeGraphContext/CodeGraphContext`	Servidor MCP y CLI que indexa código local en un grafo para asistentes de IA.	Su descripción pública habla de una base de datos de grafos; CodeGraph documenta SQLite, FTS5 y un instalador para varios agentes.
`Jakedismo/codegraph-rust`	Grafo de código y herramientas para agentes mediante MCP.	Su descripción menciona SurrealDB, análisis AST y FastML; no es un puerto confirmado de CodeGraph.
`optave/ops-codegraph-tool`	CLI local de inteligencia de código con MCP e impacto de cambios.	Declara 34 herramientas MCP y controles de arquitectura/CI, mientras CodeGraph deja una herramienta MCP visible por defecto.
`LemonCrow`	Ambos se presentan como herramientas para optimizar el contexto y coste de agentes.	La comparación de rendimiento recuperada procede del mantenedor de LemonCrow y no constituye una medición independiente.

Guía rápida de uso

Instalación y primer arranque

En macOS o Linux, el README indica este instalador autónomo; en Windows ofrece el equivalente de PowerShell:

curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh
# En una terminal nueva:
codegraph install
cd tu-proyecto
codegraph init

También se puede instalar con npm:

npm i -g @colbymchenry/codegraph

Terminal ejecutando los comandos codegraph install y codegraph init, con iconos de agentes de IA compatibles detectados automáticamente.

El instalador incorpora su propio entorno de ejecución, por lo que el README afirma que no requiere Node.js para usar CLI o MCP. codegraph install configura los agentes detectados pero no indexa ningún proyecto; codegraph init crea .codegraph/ y construye el índice. Tras instalar, hay que abrir una terminal nueva para que la ruta del ejecutable quede disponible.

Flujos de trabajo habituales

Para obtener el contexto de una tarea, ejecutar codegraph explore "cómo llega X a Y"; devuelve símbolos, código, rutas de llamada y un resumen del radio de impacto.
Para evaluar un cambio antes de editar, usar codegraph impact <símbolo>; para conocer pruebas potencialmente afectadas, codegraph affected <archivos...>.
Para una consulta puntual, usar codegraph query <búsqueda>; codegraph callers <símbolo> y codegraph callees <símbolo> recorren las relaciones directas.
El índice se actualiza automáticamente al trabajar mediante MCP. Si el observador está deshabilitado o se automatiza fuera de una sesión de agente, ejecutar codegraph sync [ruta]; codegraph status [ruta] muestra el estado y archivos pendientes.

Configuración esencial

.codegraph/: directorio por proyecto; contiene el índice local y puede eliminarse con codegraph uninit.
codegraph.json: archivo opcional para exclude, include e includeIgnored; sirve para ajustar qué código entra al índice.
.gitignore: se respeta de forma predeterminada; una negación como !vendor/ permite reintroducir una ruta excluida cuando la herramienta lo admite.
CODEGRAPH_WATCH_DEBOUNCE_MS: ajusta la espera máxima antes de sincronizar cambios; el README la limita entre 100 ms y 60 s.
CODEGRAPH_MCP_TOOLS: vuelve a exponer herramientas MCP adicionales, por ejemplo explore,node,search,callers.

Trampas frecuentes y soluciones

Instalar no equivale a indexar: si el agente no encuentra el proyecto, ejecutar codegraph init desde la raíz; install solo conecta agentes.
El comando no aparece en la misma consola: abrir una terminal nueva después del instalador.
Un bloqueo antiguo impide indexar: usar codegraph unlock [ruta] según la referencia de CLI.
Un archivo recién editado puede no estar aún en el grafo: durante la espera, leerlo directamente o comprobar codegraph status; para automatización sin observador, usar codegraph sync.
Se indexa demasiado o demasiado poco: revisar .gitignore y codegraph.json. Los directorios de dependencias, compilación, caché y archivos mayores de 1 MB se excluyen de forma predeterminada.

Integraciones y migración

codegraph install registra el servidor MCP para los agentes compatibles detectados; la integración prevista es MCP, no un complemento exclusivo de un editor. Para deshacerla, codegraph uninstall elimina configuraciones y CLI; codegraph uninstall --keep-cli conserva el ejecutable. Los índices del proyecto no se eliminan con ese comando y se quitan por separado con codegraph uninit. La documentación no describe una migración automática desde CodeGraphContext, LemonCrow u otra herramienta comparable.

Para incrustarlo como biblioteca, instalar desde npm y usar Node 22.5 o posterior; el README ofrece CodeGraph.init('/ruta/al/proyecto'), indexAll(), searchNodes(), getCallers() y getImpactRadius().

Casos de uso y a quién puede ayudar este repositorio

Personas que incorporan agentes a un repositorio existente pueden inicializar el grafo y preguntar por una ruta, símbolo o flujo, obteniendo código y relaciones en vez de empezar por búsqueda textual archivo a archivo.
Equipos que revisan cambios con riesgo de propagación pueden usar impact, callers, callees y affected para investigar dependencias y pruebas que el cambio puede alcanzar; la cobertura concreta depende de los lenguajes, marcos y patrones que la documentación enumera.
Repositorios políglotas o con una capa web y otra nativa pueden beneficiarse de la extracción de varios lenguajes y de las relaciones que el proyecto declara para rutas de marcos, puentes Swift/Objective-C y React Native/Expo. Conviene validar la cobertura en su código, especialmente ante sintaxis no compatible.
Equipos que quieren conservar el análisis dentro de su entorno pueden usar la base SQLite local y la configuración MCP sin claves de API, teniendo en cuenta la telemetría opcional: se puede desactivar con codegraph telemetry off, CODEGRAPH_TELEMETRY=0 o DO_NOT_TRACK=1.

Recursos

Repositorio: https://github.com/colbymchenry/codegraph
Documentación oficial: https://colbymchenry.github.io/codegraph/
Instalación y referencia de CLI: https://github.com/colbymchenry/codegraph#quick-start
Cambios y publicaciones: https://github.com/colbymchenry/codegraph/releases y https://github.com/colbymchenry/codegraph/blob/main/CHANGELOG.md
Paquete npm: https://www.npmjs.com/package/@colbymchenry/codegraph
Código del núcleo y pruebas: https://github.com/colbymchenry/codegraph/tree/main/codegraph-kernel y https://github.com/colbymchenry/codegraph/tree/main/__tests__
Conversaciones y comparaciones: https://news.ycombinator.com/item?id=49054696 y https://news.ycombinator.com/item?id=48994388
Comunidad/Discord: no se recuperó un enlace oficial verificable.

Nota: este artículo combina el README, la documentación y las publicaciones de CodeGraph, la API de GitHub, el registro y la API de descargas de npm, y Hacker News consultados el 6 de agosto de 2026. Las cifras cambian con el tiempo.