Graft: mapa de código para agentes de programación

Qué es un mapa del código para agentes de programación

Un mapa del código para agentes de programación es un índice persistente de su repositorio. El agente consulta este índice en lugar de recorrer el repositorio con grep desde cero en cada sesión nueva. Graft es una implementación de esta idea. Analiza el código con tree-sitter, escribe una carpeta de nodos Markdown enlazados junto con un grafo de conexiones por símbolo y ofrece herramientas de recuperación mediante MCP (model context protocol, la interfaz estándar que usan los agentes de programación para llamar a herramientas externas).

Graft no es un proxy ni una gateway. No se interpone entre el agente y la API del modelo. El mapa es una carpeta del disco que el agente lee. Esta diferencia determina qué problema se está resolviendo: un gateway de tokens autohospedado mide y enruta las solicitudes que ya envía, mientras que un mapa cambia cuántas solicitudes necesita enviar en total.

La técnica es anterior a esta herramienta y seguirá utilizándose después de ella. Aprenda primero la técnica y después los aspectos operativos.

Por qué los agentes de programación consumen contexto al redescubrir la estructura

Observe cómo un agente empieza a trabajar en un repositorio que ya ha visto cincuenta veces. Enumera los directorios. Busca un símbolo con grep. Abre tres archivos para averiguar cuál define la función y después un cuarto para saber quién la llama. Nada de eso forma parte de la tarea. Es orientación, y se paga con tokens de entrada en todas las sesiones.

La causa es sencilla. Un modelo no conserva memoria entre sesiones. Todo lo que el agente aprendió sobre su estructura estaba en una ventana de contexto que se descartó al terminar la sesión. Por tanto, el mismo proceso de descubrimiento vuelve a ejecutarse desde cero y con el coste completo. En un repositorio grande, la fase de orientación cuesta más que la edición: diez llamadas a herramientas para localizar el código y una para cambiarlo. La orientación representa una mitad de ese coste y la edición, la otra. Por eso una skill que obliga al agente a aplicar el cambio mínimo que funciona resulta útil junto con un mapa, en lugar de tener que elegir entre ambos.

Un mapa rompe ese ciclo al trasladar el descubrimiento del modelo al disco. Un analizador recorre el repositorio una vez, registra dónde se define cada símbolo y qué símbolo llama a cuál, y después mantiene ese registro actualizado cuando cambia el código. El agente formula una pregunta y obtiene una respuesta con el archivo y la línea correspondientes. La exploración repetida se convierte en una consulta barata.

Ya utiliza una versión más limitada de esto. Un archivo AGENTS.md que indica sus convenciones evita que el agente tenga que volver a deducirlas en cada ocasión. Un mapa generado evita que vuelva a deducir la estructura. La diferencia está en quién lo escribe. Usted redacta el archivo de instrucciones manualmente, por lo que se mantiene pequeño. Un analizador genera el mapa, por lo que puede abarcar diez mil archivos. Para saber cómo se distribuye realmente el presupuesto dentro de una sesión, cómo Claude Code utiliza su ventana de contexto explica el desglose.

Qué construye realmente Graft

Dos artefactos, ambos dentro de una única carpeta graft/ en la raíz del repositorio.

El primero es un grafo de nodos escrito como Markdown enlazado, con un archivo por nodo. Cada nodo contiene un resumen en inglés sencillo, un «núcleo» con las líneas de lógica importantes extraídas del código fuente, los archivos de origen exactos con un hash de contenido, wikienlaces tipados a otros nodos (depends_on, part_of, uses, implements) y una sección de notas que se conserva al regenerar el grafo, para que pueda registrar contexto que un analizador no puede inferir.

El segundo es graft/.graph/wiring.json, el grafo estructural por símbolo que extrae tree-sitter: definiciones, referencias y las relaciones de llamadas entre ellas.

La separación es importante porque sólo una de las dos partes necesita un modelo. graft build utiliza únicamente tree-sitter y nunca llama a un LLM (modelo de lenguaje grande), por lo que es determinista y no tiene coste. graft build --deep añade los resúmenes escritos y los núcleos por símbolo, que sí requieren llamadas al modelo y generan costes.

La compatibilidad con lenguajes está organizada por niveles, y el nivel indica hasta qué punto puede confiar en un grafo de llamadas. TypeScript, JavaScript, Python, Go y Java obtienen resolución entre archivos con conocimiento del ámbito. Rust, C, C++, C#, Ruby, PHP, Kotlin, Scala, Swift, Elixir, Solidity, OCaml, Zig y Dart obtienen símbolos y relaciones de llamadas genéricas. Esto significa que una relación puede basarse en una coincidencia de nombres en lugar de una referencia resuelta. Las relaciones con precisión de compilador se habilitan de forma opcional con --lsp y un servidor de lenguaje como rust-analyzer o gopls.

Instale Graft y fije la versión

Graft necesita Node.js 20 o posterior y se distribuye con licencia MIT. En agosto de 2026, la versión actual es 0.10.1 y la primera versión publicada, 0.1.0, está fechada en julio de 2026. Trátelo como software reciente.

npm install -g @nanonets/graft@0.10.1
npm ls -g @nanonets/graft

npm ls -g debe mostrar @nanonets/graft@0.10.1. Fije esa versión de forma explícita. Un npm install -g @nanonets/graft sin versión resuelve la etiqueta latest en el momento de ejecutarlo. En un proyecto que publica varias versiones menores al mes, esto hace que el martes tenga una herramienta distinta de la que su compañero instaló el lunes. Una versión fijada mantiene iguales para todos las opciones de la CLI y el formato del grafo, de modo que usted actualiza cuando lo decide.

A continuación, integre Graft en un repositorio que administre:

cd /path/to/your/repo
graft init --dry-run
graft init

graft init pregunta con cuáles de sus agentes de programación quiere integrarlo y después crea el grafo. Ejecute primero --dry-run y revise la lista de archivos que planea modificar, porque algunos pueden estar fuera del repositorio. graft init es idempotente y no sobrescribe las configuraciones existentes, por lo que es seguro ejecutarlo una segunda vez.

En agosto de 2026, la integración cubre Claude Code, Cursor, Codex, GitHub Copilot, Google Gemini, Kiro, Windsurf y AdaL. Claude Code obtiene la integración más completa: una entrada de servidor MCP, una línea de estado que muestra el tamaño y la antigüedad del grafo, hooks posteriores a la edición que vuelven a crear el grafo y un archivo de skill en .claude/. Los demás reciben un archivo de instrucciones o reglas que informa al agente de que las herramientas existen. Por tanto, «compatible» significa que Graft escribe la integración. Si un agente omite su propio archivo de reglas, también omitirá el mapa. Esa es la razón habitual por la que los agentes ignoran las instrucciones que usted les escribe, y aquí se aplica igual que en cualquier otro caso.

Qué entra en el repositorio y qué queda fuera de git

Después de graft init, espere estos cambios:

• graft/: el grafo de nodos de Markdown y graft/.graph/wiring.json. Se añade a .gitignore automáticamente.
• .mcp.json: registra el servidor MCP de graft para que Claude Code lo inicie.
• .claude/settings.json: se integra en el archivo existente y añade la línea de estado y los hooks posteriores a la edición.
• AGENTS.md, GEMINI.md, .github/copilot-instructions.md, .cursor/rules/graft.mdc, .kiro/steering/graft.md, .windsurf/rules/graft.md y .adal/skills/graft/SKILL.md: secciones delimitadas por marcadores que se añaden a los archivos que correspondan a los agentes seleccionados.
• ~/.codex/config.toml, ~/.codex/hooks.json y ~/.codex/hooks/graft/graft-hooks.cjs: tienen alcance para todo el equipo y sólo se escriben al seleccionar Codex. graft init --no-global omite estos archivos y graft init --no-hooks omite por sí solo el adaptador del hook.

El grafo es una caché, como node_modules. No lo confirme en el repositorio. Se regenera a partir del código en unos segundos, cambia con casi cada edición y, si lo confirma, convierte una corrección de una línea en un diff de varios cientos de archivos que ningún revisor leerá. Confirme en su lugar la integración, incluidos AGENTS.md y .mcp.json. Un compañero clona el repositorio, ejecuta graft build y obtiene su propio grafo local.

Compruebe que la regla de exclusión se haya añadido antes de hacer su primer commit:

grep -n graft .gitignore
git status --short

grep debería mostrar una línea que contenga graft/, y git status --short no debería mostrar nada dentro de graft/. Si aparecen archivos de graft/ en esa salida, significa que falta la entrada de exclusión o que otra configuración la está sobrescribiendo. Corríjalo antes de hacer el commit, porque git sigue realizando el seguimiento de un archivo después de añadirlo, y una edición posterior de .gitignore no dejará de seguirlo.

Si prefiere registrar manualmente el servidor MCP o fijarlo a la misma versión que instaló, la entrada es pequeña:

{
  "mcpServers": {
    "graft": {
      "command": "npx",
      "args": ["-y", "@nanonets/graft@0.10.1", "mcp"]
    }
  }
}

Las herramientas de consulta que usa el agente en lugar de grep

Graft expone seis herramientas mediante MCP. graft_find_code devuelve nodos ordenados por relevancia para una descripción de tarea, junto con el archivo y la línea. graft_file_api devuelve todas las firmas de un archivo sin los cuerpos. graft_trace_calls recorre los llamadores o las funciones llamadas durante varios niveles. graft_find_all devuelve las coincidencias de una expresión regular agrupadas por símbolo. graft_repo_map ofrece una primera vista de un repositorio desconocido. graft_check_freshness indica si el grafo sigue coincidiendo con el código.

Cada herramienta tiene un equivalente en la CLI. Esta es la forma de comprobar qué recibe realmente el agente:

graft map .
graft ask "where do we validate the refresh token"
graft skeleton src/auth/session.ts
graft callers validateRefreshToken
graft callers validateRefreshToken --direction out
graft grep "refresh_token" --json

graft ask debería mostrar nodos ordenados por relevancia con referencias file:line, no el contenido de los archivos. Ese es todo el mecanismo: el agente recibe un puntero y abre un archivo, en lugar de leer diez para encontrar el correcto. graft viz abre un visor interactivo en localhost si quiere examinar el grafo directamente. Si graft ask no devuelve información útil para una pregunta que podría responder en treinta segundos, el grafo está desactualizado o su lenguaje pertenece al nivel amplio, y el mapa tampoco ayudará al agente.

Hay un coste fácil de pasar por alto. Las seis definiciones de herramientas se inyectan en el prompt del sistema de cada solicitud durante toda la sesión. Ese coste se aplica tanto si el agente usa el mapa como si no. En un repositorio lo bastante pequeño para caber en el contexto, el coste fijo puede ser mayor que la exploración que evita.

Qué ocurre con el grafo cuando cambia el código

La actualización estructural es rápida y automática. Graft lee el árbol de trabajo, no git, por lo que tanto una edición que aún no ha confirmado como una edición que ha preparado son visibles para la herramienta. Una consulta vuelve a analizar sólo los archivos cuyo estado haya cambiado. El proyecto documenta este coste como aproximadamente 3 ms. La reconstrucción al final de un turno sólo afecta a los archivos en los que se haya movido código. Use GRAFT_NO_REFRESH=1 o pase --no-refresh para responder desde el grafo almacenado en disco sin volver a analizarlo. Pase --no-reuse para forzar un análisis completo desde cero. Esto es lo que debe hacer después de actualizar Graft.

La mitad escrita por el modelo se comporta de otra forma. Es la parte que puede fallar sin avisar. Los resúmenes y los puntos críticos se almacenan en caché. Cada nodo registra un hash de contenido de sus fuentes. Cuando cambia un archivo fuente, el nodo se marca como obsoleto en lugar de presentarse como actualizado. Esa marca sólo sirve si algo actúa sobre ella. Actualice con graft build --deep. Esto vuelve a consumir tokens del modelo.

Haga visible la obsolescencia:

graft check .
echo $?

El estado de salida 0 significa que el grafo coincide con el código. El estado de salida 1 significa que hay divergencias. Ejecútelo desde un hook pre-push o sobre la rama en CI, para que un mapa de hace seis meses no responda con seguridad sobre código que se reescribió en marzo.

Lea con atención las cifras de los benchmarks publicados

La afirmación principal de Graft es «hasta 4 veces más barato y 3 veces más rápido, con una corrección igual o mejor». Estas cifras proceden de los propios benchmarks del proyecto, publicados en su README. A continuación se muestran completas las dos ejecuciones que informa.

[
  {
    "label": "Controlled sweep",
    "run_count": 162,
    "token_saving_pct": 42,
    "tool_call_saving_pct": 46,
    "correctness_pct": 93,
    "baseline_correctness_pct": 93
  },
  {
    "label": "SWE-bench Verified",
    "run_count": 50,
    "token_saving_pct": 23,
    "tool_call_saving_pct": 25,
    "correctness_pct": 66,
    "baseline_correctness_pct": 54
  }
]

La evaluación controlada incluye 162 ejecuciones sobre dos repositorios, uno de ellos Graft, con tres pruebas por tarea. Informa de un 42% menos de tokens y un 46% menos de llamadas a herramientas. La ejecución de SWE-bench Verified incluye 50 instancias con el mismo modelo en ambas variantes, y muestra un ahorro menor: 23% de los tokens y 25% de las llamadas a herramientas. Una tercera ejecución reprodujo cinco pull requests de PocketBase que se habían fusionado, con un coste de 11.02 dólares estadounidenses frente a 13.91 para la línea base.

Trate todo esto como un benchmark del proveedor. Hay dos factores que limitan lo que puede indicar. La evaluación controlada incluye el propio repositorio de Graft, que es la base de código con la que sus autores han ajustado la herramienta. SWE-bench Verified es un conjunto de datos público con incidencias de proyectos Python de código abierto conocidos, y las herramientas se optimizan para los conjuntos de datos públicos, aunque nadie lo haga de forma intencionada. Ninguno de los dos resultados describe su monorepo privado, que tiene sus propias convenciones de nombres y su propio código obsoleto.

La corrección requiere una segunda lectura. En la evaluación controlada no cambió: 93% con el mapa frente a 93% sin él. El aumento a 66% desde 54% aparece únicamente en SWE-bench Verified. Una herramienta que reduce el coste de los tokens y mantiene estable la calidad sigue siendo una buena opción. No traslade el resultado de corrección de SWE-bench al resultado de tokens de la evaluación controlada ni presente ambos como una sola afirmación.

Mida tu propio delta de tokens antes de creer nada de esto

El único número que importa es el de tu repositorio. Este método requiere una tarde.

Elige una tarea que puedas repetir exactamente. Una pregunta es mejor que una edición, porque una edición modifica el repositorio y la segunda ejecución ya no es el mismo experimento. «Qué módulo aplica el límite de tasa en la ruta de inicio de sesión» tiene el formato adecuado.

Activa la telemetría y envíala a tu propia terminal:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console
claude

El exportador de consola imprime los registros de métricas a medida que se recopilan. El que necesitas es claude_code.token.usage, que contiene un atributo type con el valor input, output, cacheRead o cacheCreation. La orientación aparece en input y cacheRead, porque ahí se incluye el contenido de los archivos. Suma esos dos valores.

Ejecuta la tarea tres veces, cada vez en una sesión nueva, con el mapa conectado. Después elimina la entrada de injerto de .mcp.json y ejecútala tres veces más. Compara las medianas en lugar de ejecuciones individuales, porque las ejecuciones del agente varían mucho y una ejecución desafortunada puede indicar lo contrario de la realidad. Registra también el número de llamadas a herramientas: las llamadas a herramientas son el mecanismo y los tokens son el efecto, por lo que ahorrar tokens sin reducir las llamadas a herramientas significa que ha cambiado otra cosa.

Después resta los costes que el benchmark no muestra. graft build --deep consume tokens del modelo en cada actualización completa. Los seis esquemas de herramientas se incluyen en cada solicitud. Si tus agentes se ejecutan en un servidor alquilado, establecer un límite estricto para el gasto del agente convierte esto de una sorpresa en un presupuesto, y qué informa realmente la telemetría de un agente de programación explica qué sale de la máquina cuando activas el exportador.

¿Cuándo deja de ser útil un mapa del código?

• El repositorio ya cabe en el contexto. Un servicio pequeño y único no necesita un mapa, y en cada solicitud sigues pagando seis esquemas de herramientas. Si hoy tu agente encuentra cualquier archivo con una o dos llamadas a herramientas, omítelo.
• Tu lenguaje está en el nivel amplio. Las relaciones de llamadas genéricas hacen que graft callers no encuentre un llamador o genere uno por una colisión de nombres. Confírmalo con graft grep antes de confiar en el alcance del impacto.
• El grafo quedó obsoleto y nadie lo advirtió. graft check termina con el código 1 cuando detecta divergencias, pero eso sólo sirve si algo lo ejecuta. Usa un hook o un paso de CI, no una ejecución manual ocasional.
• El monorepo necesita delimitación. Un monorepo gestionado con un solo repositorio Git se divide automáticamente mediante el archivo de workspace, go.mod, pyproject.toml o Cargo.toml, y graft ask "..." --in services/billing/ limita una consulta a un solo subproyecto. El mismo criterio que lleva a usar archivos AGENTS.md anidados por paquete se aplica al mapa.
• El agente ignora las conexiones. Observa las llamadas a herramientas durante una sesión real antes de concluir que el mapa se está usando. Si el agente sigue ejecutando grep, indica que nunca leyó el archivo de reglas.

FAQ

¿Debo incluir la carpeta graft/ en git?

No. graft build añade graft/ a tu .gitignore automáticamente, porque el grafo es una caché regenerable, como node_modules. Cambia con casi cada edición, por lo que incluirla en los commits oculta las diferencias reales bajo cientos de archivos generados. Incluye en el commit la configuración que indica a los agentes que el mapa existe, incluidos AGENTS.md y .mcp.json, y deja que cada miembro del equipo ejecute graft build localmente. Compruébalo con grep -n graft .gitignore y git status --short antes de tu primer commit, porque git sigue controlando un archivo después de añadirlo y editar .gitignore posteriormente no hace que deje de estar controlado.

¿Cuesta dinero ejecutar Graft?

La parte estructural no. graft build, graft ask, graft check y las seis herramientas de recuperación MCP son operaciones de tree-sitter que nunca llaman a un modelo. graft build --deep es la parte de pago: escribe los resúmenes en inglés sencillo y los puntos clave de cada símbolo mediante un LLM, configurado con GRAFT_PROVIDER, GRAFT_API_KEY y GRAFT_MODEL, además de GRAFT_BASE_URL para cualquier endpoint compatible con OpenAI. Puedes ejecutar Graft sólo con la estructura y no gastar ningún token en el grafo.

¿Cuánto puede ahorrar realmente un mapa del código en mi repositorio?

Nadie puede decirlo sin medirlo. El proyecto informa de un 42% menos de tokens en su propio análisis de 162 ejecuciones y de un 23% en SWE-bench Verified, ambos frente a una referencia sin mapa. Son benchmarks del proveedor; uno de ellos se ejecutó parcialmente sobre el propio repositorio de Graft y ninguno describe tu código privado. Ejecuta una misma pregunta reproducible tres veces con el mapa y tres veces sin él, con CLAUDE_CODE_ENABLE_TELEMETRY=1 y OTEL_METRICS_EXPORTER=console configurados. Después, compara la mediana de claude_code.token.usage para los tipos input y cacheRead.

¿Qué ocurre con el grafo cuando refactorizo?

La estructura se vuelve a analizar automáticamente. Graft analiza el árbol de trabajo y vuelve a analizar sólo los archivos que han cambiado. Por eso, un cambio de nombre se detecta en la siguiente consulta con una sobrecarga aproximada de 3 ms. También detecta el trabajo sin commit porque lee los archivos, no el historial de git. Los resúmenes escritos por el modelo son los que quedan obsoletos: cada nodo almacena un hash de contenido de sus fuentes, y una fuente modificada marca el nodo como obsoleto en lugar de volver a escribirlo. Ejecuta graft check . para ver la desviación y después graft build --deep para actualizar la parte escrita.

¿Qué agentes de programación pueden usar Graft actualmente?

En agosto de 2026, graft init integra Claude Code, Cursor, Codex, GitHub Copilot, Google Gemini, Kiro, Windsurf y AdaL. Claude Code recibe la integración más completa: una entrada de servidor MCP en .mcp.json, una línea de estado, hooks posteriores a la edición y un archivo de skills en .claude/. Codex recibe una sección AGENTS.md y entradas de ámbito global del equipo en ~/.codex/, que graft init --no-global omite. Los demás reciben un archivo de reglas o de directivas. Cualquier otro cliente MCP puede usar directamente el servidor registrando el comando npx -y @nanonets/graft@0.10.1 mcp.