Trabajar con asistentes de programación basados en IA tiene una parte incómoda que muchos desarrolladores ya han sufrido: antes de proponer una solución, el modelo necesita entender el proyecto. Y para entenderlo suele recorrer archivos, buscar símbolos, lanzar consultas con grep, abrir módulos, revisar imports y pedir contexto una y otra vez. Cada una de esas operaciones consume tiempo, llamadas a herramientas y, en muchos casos, tokens.
CodeGraph nace para reducir ese coste. El proyecto, disponible en GitHub bajo licencia MIT, crea un grafo semántico local del código para que herramientas como Claude Code, Cursor, Codex CLI y OpenCode puedan consultar la estructura del proyecto sin explorar todo desde cero en cada tarea. La idea es sencilla: indexar una vez el repositorio, guardar relaciones entre símbolos, llamadas, imports, clases, métodos y rutas, y permitir que el agente consulte esa base local cuando necesite contexto.
El enfoque encaja con una tendencia clara en el desarrollo asistido por IA. A medida que los proyectos crecen, no basta con darle al modelo una carpeta y pedirle que “entienda” el código. El contexto se vuelve caro, las búsquedas son repetitivas y los agentes pueden perder tiempo leyendo archivos que no aportan nada. Un índice semántico local reduce esa exploración inicial y permite que la IA vaya antes a las partes relevantes.
Qué hace CodeGraph y por qué puede ahorrar tokens
CodeGraph funciona como una capa de inteligencia sobre el repositorio. Analiza el código con tree-sitter, extrae nodos como funciones, clases, métodos o archivos, y crea relaciones entre ellos: llamadas, imports, herencia, implementaciones y referencias. Todo se guarda en una base de datos SQLite dentro del propio proyecto, en .codegraph/codegraph.db, con búsqueda de texto completo mediante FTS5.
Esto significa que, cuando un agente necesita localizar dónde se implementa el login, qué funciones llaman a un servicio o qué tests podrían verse afectados por un cambio, no tiene que recorrer todo el árbol de archivos. Puede consultar el grafo.
Según los datos publicados por el proyecto, sus benchmarks sobre seis repositorios reales muestran una media del 92 % menos de llamadas a herramientas y un 71 % más de rapidez al explorar código. En la cabecera del repositorio también se destacan mediciones de hasta un 94 % menos de llamadas y un 77 % de mejora en velocidad de exploración, aunque conviene leer estas cifras como resultados del propio proyecto y no como una garantía universal para cualquier código base.
| Proyecto probado | Con CodeGraph | Sin CodeGraph | Mejora indicada |
|---|---|---|---|
| VS Code | 3 llamadas, 17 s | 52 llamadas, 1 min 37 s | 94 % menos llamadas, 82 % más rápido |
| Excalidraw | 3 llamadas, 29 s | 47 llamadas, 1 min 45 s | 94 % menos llamadas, 72 % más rápido |
| Claude Code, Python + Rust | 3 llamadas, 39 s | 40 llamadas, 1 min 8 s | 93 % menos llamadas, 43 % más rápido |
| Claude Code, Java | 1 llamada, 19 s | 26 llamadas, 1 min 22 s | 96 % menos llamadas, 77 % más rápido |
| Alamofire | 3 llamadas, 22 s | 32 llamadas, 1 min 39 s | 91 % menos llamadas, 78 % más rápido |
| Swift Compiler | 6 llamadas, 35 s | 37 llamadas, 2 min 8 s | 84 % menos llamadas, 73 % más rápido |
La ventaja no está solo en ahorrar tokens. También mejora el flujo de trabajo. Un agente que comprende antes el proyecto puede dedicar más tiempo a razonar sobre el cambio y menos a reconstruir mentalmente la arquitectura. En tareas de refactorización, corrección de bugs o análisis de impacto, eso puede marcar una diferencia notable.
Local, open source y compatible con varios agentes
Uno de los puntos fuertes de CodeGraph es que se ejecuta en local. No requiere claves de API, no envía el código a servicios externos y guarda el índice en SQLite. Para equipos que trabajan con repositorios privados, propiedad intelectual o código de clientes, este detalle es importante. La IA ya puede tener sus propias implicaciones de privacidad, pero al menos la capa de indexación del proyecto no añade una nueva dependencia externa.
La instalación está pensada para ser rápida. El comando inicial es:
npx @colbymchenry/codegraph
El instalador interactivo detecta agentes compatibles y puede configurar Claude Code, Cursor, Codex CLI u OpenCode. Después, dentro del proyecto, basta con ejecutar:
codegraph init -i
Ese comando crea el índice local y deja el repositorio preparado para que el agente use CodeGraph automáticamente cuando detecte la carpeta .codegraph/.
También hay opciones para instalación no interactiva, útil en entornos de scripting o CI, y comandos manuales para indexar, sincronizar, consultar símbolos, listar archivos, construir contexto o analizar qué tests se ven afectados por cambios concretos.
CodeGraph expone además herramientas MCP, lo que permite que los agentes compatibles consulten el grafo de forma estructurada. Entre ellas están codegraph_search, para buscar símbolos; codegraph_context, para construir contexto útil para una tarea; codegraph_callers y codegraph_callees, para ver llamadas entrantes y salientes; codegraph_impact, para analizar el radio de impacto de un cambio; y codegraph_files, para obtener la estructura indexada del proyecto sin escanear el sistema de archivos.
Lenguajes, frameworks y rutas web
La cobertura de lenguajes es amplia. CodeGraph declara soporte completo para TypeScript, JavaScript, Python, Go, Rust, Java, C#, PHP, Ruby, C, C++, Swift, Kotlin, Scala, Dart, Svelte, Vue, Liquid y Pascal/Delphi, entre otros. Esto lo hace útil tanto para aplicaciones web modernas como para repositorios de backend, herramientas de sistemas, SDKs o proyectos móviles.
Otro detalle interesante es su soporte para rutas de frameworks web. CodeGraph puede reconocer patrones de routing en Django, Flask, FastAPI, Express, Laravel, Rails, Spring, Gin, chi, gorilla/mux, Axum, actix, Rocket, ASP.NET, Vapor, React Router y SvelteKit. En la práctica, esto permite conectar URLs o rutas con los handlers correspondientes, algo muy útil cuando un agente debe entender cómo llega una petición HTTP a una función concreta.
Por ejemplo, si una IA tiene que modificar el comportamiento de una vista, no siempre basta con encontrar el método. También necesita saber qué ruta lo invoca, qué middleware puede intervenir, qué controlador lo envuelve y qué otros puntos dependen de ese símbolo. Un grafo de código ayuda a responder esas preguntas con menos exploración repetida.
La herramienta también incluye sincronización automática. El servidor MCP observa cambios en el proyecto mediante eventos nativos del sistema operativo, como FSEvents, inotify o ReadDirectoryChangesW, y actualiza el índice de forma incremental tras una ventana de espera. Así, el grafo no queda obsoleto cada vez que se guarda un archivo.
Dónde encaja y dónde conviene tener cuidado
CodeGraph puede ser especialmente útil en repositorios medianos o grandes, equipos que usan agentes de programación a diario, proyectos con muchos módulos o aplicaciones donde el coste de exploración del código empieza a ser evidente. También puede ayudar en tareas de onboarding, análisis de impacto y selección de tests afectados por cambios.
No sustituye al criterio del desarrollador ni convierte a la IA en infalible. El grafo puede acelerar la búsqueda de contexto, pero el modelo aún debe interpretar correctamente la intención del cambio. También hay que vigilar la calidad del índice, las carpetas excluidas, el tamaño máximo de archivos y el backend de SQLite. El propio proyecto advierte de que, si se usa la versión WASM de SQLite en lugar del backend nativo better-sqlite3, el rendimiento puede ser entre 5 y 10 veces más lento y aparecer bloqueos de base de datos durante la indexación.
La configuración permite excluir carpetas como node_modules, dist o build, definir lenguajes, activar extracción de docstrings y controlar el seguimiento de llamadas. En proyectos grandes, ajustar bien esas opciones será importante para evitar índices innecesariamente pesados.
La lectura de fondo es clara: el futuro del desarrollo con IA no dependerá solo de modelos más grandes. También dependerá de mejores herramientas para darles contexto. Un agente que entiende la estructura del proyecto sin leerlo entero en cada petición trabaja con menos ruido, menos coste y más precisión. CodeGraph apunta justo ahí: convertir el repositorio en un mapa consultable, local y preparado para agentes.
Preguntas frecuentes
¿Qué es CodeGraph?
CodeGraph es una herramienta open source que crea un grafo semántico local del código para que agentes de IA como Claude Code, Cursor, Codex CLI y OpenCode entiendan mejor un proyecto sin explorarlo desde cero.
¿CodeGraph envía el código a la nube?
No. Según la documentación del proyecto, funciona de forma local, no requiere API keys y guarda el índice en una base de datos SQLite dentro del proyecto.
¿Qué ventajas aporta frente a búsquedas normales con grep?
Además de buscar texto, CodeGraph entiende símbolos, llamadas, imports, relaciones entre clases y rutas de frameworks. Esto permite construir contexto más útil para tareas de programación asistida por IA.
¿Qué lenguajes soporta CodeGraph?
Soporta más de 19 lenguajes, entre ellos TypeScript, JavaScript, Python, Go, Rust, Java, C#, PHP, Ruby, C, C++, Swift, Kotlin, Dart, Svelte, Vue y Pascal/Delphi.
