El impuesto de exploración: Por qué tu IA a veces da tantas vueltas

Todas las que usamos Claude Code conocemos esa sensación. Abres una sesión nueva, lanzas tu consulta y observas cómo el agente empieza a divagar:

⏺ Explore(“¿Cómo se comunica el host de extensiones con el proceso principal?”)

⎿ Hecho (52 usos de herramientas · 89.4k tokens · 1m 37s)

Es agotador. Cada. Maldita. Vez.

Como Claude no tiene memoria de tu base de código, empieza a lanzar agentes de exploración que recorren todo mediante llamadas constantes de grep, glob y lectura de archivos. Cada pequeña llamada consume tokens y, lo que es peor, cada archivo escaneado reduce tu valiosa ventana de contexto.

Lo medí en uno de mis proyectos: 60 llamadas a herramientas y 157,800 tokens. Casi 2 minutos de espera antes de que Claude siquiera comenzara a trabajar en lo que realmente necesitaba. Y la parte más frustrante es que, al cerrar la sesión, todo ese conocimiento costoso se esfuma. ¿Abres otra? Empezamos desde cero. Es un "impuesto de exploración" que pagamos constantemente.

Las soluciones que se quedan a medias

No soy la única que ha notado esto, y la comunidad ha intentado poner parches:

  • Archivos Markdown de memoria: Esas notas en CLAUDE.md con resúmenes y arquitectura. Ayudan un poco, pero Claude sigue sin entender las relaciones reales; solo está leyendo un documento estático.
  • Subagentes con archivos compartidos: Sistemas elaborados donde los agentes actualizan archivos de memoria. Es mejor, pero sigue siendo un arreglo improvisado. Falta estructura.
  • Relleno manual de contexto: Copiar y pegar código antes de preguntar. Funciona, sí, pero es tedioso y, seamos sinceras, no escala.

Nada de esto le da a Claude lo que realmente necesita: entender cómo está conectado tu código.

¿Y si los agentes de exploración tuvieran un mapa?

Esa es la idea detrás de CodeGraph. En lugar de escanear archivos a ciegas, los agentes consultan un grafo de código preconstruido que entiende perfectamente:

  • Qué funciones llaman a cuáles.
  • Qué clases heredan de qué otras.
  • Dónde se implementan las interfaces.
  • Cómo los imports conectan los archivos.
  • Cuál es el radio de impacto real cuando tocas algo.

No es un resumen que la IA tenga que interpretar; es una base de datos estructurada a la que Claude puede preguntar directamente. Los agentes siguen trabajando, pero son infinitamente más eficientes. Las consultas al grafo son instantáneas, eliminando el escaneo archivo por archivo.

⏺ Explore(“¿Cómo se comunica el host de extensiones con el proceso principal?”)

⎿ Hecho (3 usos de herramientas · 56.6k tokens · 17s)

La clave es codegraph_explore, una sola herramienta que devuelve secciones completas del código fuente para cada símbolo relevante. Adiós a las 52 llamadas separadas; ahora, una sola consulta al grafo le da a la IA todo lo que necesita.

Datos reales: El impacto es innegable

Ejecuté el mismo prompt con y sin CodeGraph activado en toda la base de código de VSCode. El veredicto es claro: los agentes utilizan aproximadamente un 94% menos de llamadas a herramientas y son cerca de un 82% más rápidos. Esto se traduce en un ahorro directo de dinero, tokens y tiempo.

Configuración en 5 minutos

¿Te animas a probarlo? Solo necesitas Node.js 18+ y Claude Code. Ejecuta este comando:

npx @colbymchenry/codegraph

El instalador interactivo se encarga de todo: configura el servidor MCP en ~/.claude.json, ajusta los permisos y te pregunta si deseas inicializar tu proyecto. Luego, simplemente reinicia Claude Code y corre:

codegraph init -i

En unos 30 segundos, tendrás miles de archivos indexados, nodos mapeados y relaciones listas.

¿Cómo funciona la magia?

CodeGraph analiza tu base de código mediante tree-sitter y guarda todo en una base de datos SQLite local. Claude Code se conecta vía MCP y consulta este grafo cuando necesita entender algo. Además, usa un FileWatcher que monitorea cambios en tiempo real, resincronizando todo en menos de un segundo.

¿Qué ganas con esto?

  • Construcción inteligente de contexto: Análisis más rápido y ahorro masivo de tokens.
  • Análisis de impacto: Saber qué se puede romper antes de cambiar nada.
  • Compatibilidad total: Funciona con más de 19 lenguajes (de TypeScript a Rust, Go, Python y más).
  • Privacidad 100% local: Ningún dato sale de tu máquina. Sin claves API externas.
  • Detección de tests afectados: Ejecuta solo lo necesario integrando git diff para tus procesos de CI.

Detalles técnicos para profundizar

CodeGraph extrae nodos (funciones, clases, métodos) y relaciones (llamadas, imports, herencias) usando una arquitectura robusta:

  1. Motor de análisis: Tree-sitter para extraer ASTs.
  2. Almacenamiento: SQLite local con búsqueda FTS5.

Herramientas MCP:

  • codegraph_context: Para contexto completo.
  • codegraph_search: Búsqueda rápida de símbolos.
  • codegraph_callers / codegraph_callees: Para rastrear relaciones.
  • codegraph_impact: Para calcular el efecto de tus cambios.

La resolución de referencias es fina: empareja llamadas, resuelve imports complejos y entiende patrones de frameworks, dándole a Claude una visión estructurada de tu trabajo.

Gracias por leer Código en Casa.
Si esto te a ayudado y te sumo algo Dale un 👏 , compártelo con tu red o dejame un comentario para saber tu opinión.