Graft: capa de contexto para coding agents con 42% menos tokens

Si usás Claude Code, Cursor o Codex todos los días, ya te pasó: arrancás una tarea y el agente se pierde los primeros cinco minutos haciendo grep, cat, abriendo archivos, retrocediendo, intentando de nuevo. Está reconstruyendo un mapa del repo que vos ya tenés en la cabeza, o que podría construirse una sola vez y reutilizarse. Eso es exactamente lo que ataca Graft, el proyecto open-source que NanoNets publicó el 13 de agosto: un grafo de tu codebase escrito en archivos markdown, commiteado en el repo, que el coding agent consulta por hooks en cada turno. Midieron 162 runs controlados y los números son de los que duelen: 42% menos tokens, 46% menos tool calls, 60% menos tiempo, y 66% de SWE-bench Verified contra 54% del mismo agente sin graft. Es el ángulo que faltaba en la conversación sobre coding agents que veníamos cubriendo en permission fatigue y tokenpocalypse — ya no es un problema de permisos ni de precio por token, es un problema de qué contexto le metés al modelo y cuándo.

Qué es Graft en una linea

Una capa de contexto que construye un grafo de tu repo una sola vez, lo escribe como archivos markdown linked en graft/, y lo inyecta al coding agent en cada turno vía hooks. Sin base de datos, sin embeddings, sin servidor, sin daemon. El grafo es texto, y git lo commitea junto con tu código.

Lo que cambia respecto a RAG tradicional: Graft no hace similarity search, no corre un index, no te cobra por embeddings. El grafo son archivos .md que el agente abre con Read y sigue con links, igual que lee cualquier otro archivo del repo. Si el grafo queda desactualizado, lo ves como un diff en PR review, no como un índice podrido en un store externo.

El flow de setup es de dos comandos:

npm install -g @nanonets/graft
graft init

graft init pregunta qué coding agents querés wirear (Claude Code, Cursor, Codex, Gemini), construye el grafo, y mete un statusline + hooks en .claude/ (o el directorio equivalente del agente). A partir de la próxima sesión, Graft viene "pegado" al flujo: trae los nodos relevantes a cada prompt y rebuildea el grafo en background después de cada turno.

Por que el "mapa del repo" es el verdadero cuello de botella

Cualquiera que use Claude Code con codebase mediana lo vivió: el agente se traga entre el 30% y el 50% de su budget de tokens en exploración. Abre el archivo equivocado, lee 800 líneas para entender una función, se da cuenta que necesita otro módulo, vuelve a buscar, lee otro, conecta los puntos tarde. La métrica que NanoNets midió es exactamente esta:

"Every task, your coding agent starts blind. Before it changes anything, it re-explores the repo: grep a term, open a file, follow an import, back out, try again. It is rebuilding a picture of a codebase it mapped an hour ago and threw away." — README de Graft

Es la descripción perfecta de por qué Claude Opus 5 se siente brillante en sesiones cortas y se cae en sesiones largas. El modelo no cambió; cambió el mar de archivos irrelevantes que tiene que filtrar mentalmente. Un mapa precomputado invierte la carga: el agente llega a la tarea con un índice mental del sistema, no con una pizarra en blanco.

Los numeros de la benchmark de NanoNets

Corrieron tres variantes del mismo Claude Sonnet 5 con los mismos file tools: cold (explora desde cero), graft (recibe un bundle graft ask --source up front), y pull (tools graft_find_code/graft_file_api que se llaman on-demand, contexto se paga solo cuando se pide). 162 runs sobre dos repos (graft mismo y un servicio Node/Express de auth real), 3 trials por tarea, mezcla de single-file y multi-file.

Variante	Tool calls	Tokens	Tiempo	SWE-bench
Cold Claude Code	baseline	baseline	baseline	54%
Claude Code + graft (push)	-46%	-42%	-60%	66%
Claude Code + graft (pull)	-38%	-31%	-52%	63%

El detalle más importante: no hubo trade-off de calidad. Un juez Opus 4.8 evaluó correctness con keyword-floor obligatorio, así que un resultado rápido-pero-incorrecto no podía ganar por velocidad. La diferencia de 12 puntos en SWE-bench (66% vs 54%) es de las que normalmente se anuncian como "major model upgrade". Acá no se tocó el modelo: se tocó el contexto que se le inyecta.

El detalle metodológico que importa: los costos son cache-aware. Reads ≈ 0.1×, writes 1.25×, el modelo de billing que los coding agents realmente facturan. No es una métrica "teórica en tokens" sino lo que sale de la tarjeta.

Como funciona el grafo por dentro

El output de graft init no es un JSON opaco: es un árbol de archivos markdown en graft/ con un nodo por sistema, API o concepto. Cada nodo linkea a los archivos del repo que lo implementan y a los otros nodos relacionados. Ejemplo esquemático:

# graft/auth-node

> User authentication subsystem. Handles login, token issuance,
> session refresh, and rate limiting. Backed by Postgres.

## Files
- src/auth/login.ts
- src/auth/middleware.ts
- src/auth/refresh.ts
- migrations/2026_01_auth.sql

## Related
- [[graft/sessions-node|Sessions]]
- [[graft/rate-limit-node|Rate limiting]]
- [[graft/users-schema|Users table]]

## Public API
- `POST /auth/login`
- `POST /auth/refresh`
- `GET /auth/me`

El coding agent, en vez de abrir src/auth/login.ts y leerlo de punta a punta, abre graft/auth-node.md (50 líneas), ve qué archivos tocar, qué endpoints existen, qué subsistemas se relacionan, y va directo. Si necesita ver la implementación de un endpoint, va al archivo puntual. Menos archivos leídos, menos tokens quemados, menos round-trips de grep.

Tres modos de integración, no uno

Lo que me parece más interesante del diseño es que no te obligan a elegir entre "todo el contexto siempre" o "nada":

• Push mode (graft ask --source): el bundle se inyecta al inicio de cada prompt. Es el que da los mejores números (-46% tool calls, 66% SWE-bench). El trade-off es que paga contexto aunque la tarea no lo necesite.
• Pull mode (MCP server): el agente llama a graft_find_code y graft_file_api cuando necesita. Paga contexto solo cuando lo usa (-31% tokens), pierde ~3 puntos de SWE-bench.
• Deep integration con Claude Code: hooks en .claude/settings.json que disparan automáticamente según el evento (pre-tool-use, post-tool-use). Es el más fino y el que requiere entender el sistema de hooks de Claude Code.

Si venís tuneando agentes que se hablan entre sesiones, el pull mode te queda cómodo. Si querés el "fire and forget" sin pensar, push mode. Si tu flujo es 90% Claude Code, deep integration.

Por que importa que sea opt-in progresivo: los coding agents no son todos iguales. Cursor usa un modelo de contexto distinto, Codex maneja tools de otra forma, Gemini trae grounding propio. Graft no te pide que migres de herramienta — se enchufa encima de la que ya usás.

La decision de diseño que mas me gusta: grafo commiteado, no index externo

Esta es la movida que separa a Graft de los approaches tipo "smart context" que ya probamos:

1. El grafo es código. Va en graft/ dentro del repo. Cualquiera que clone el proyecto lo tiene. No hay un servicio central que mantener, ni un cache que se pudra.
2. Los PRs lo actualizan. Si cambias auth/login.ts y rompés la coherencia del grafo, sale como diff en el code review. Tu reviewer humano lo ve, te pide que regeneres el nodo, y queda versionado con la historia del repo.
3. Sin vendor lock-in. El formato es markdown. Si mañana NanoNets desaparece, vos tenés graft/auth-node.md legible por cualquier agente. No es un .graft binario que solo abre su tool.
4. El grafo es legible por humanos. Un dev nuevo en el equipo puede abrir graft/ y leer la arquitectura del sistema como quien lee documentación. Es wiki + índice + mapa, todo en uno.

Si trabajás en PRs chicos stacked, el grafo commiteado es una pieza más del diff. Si trabajás con agentes, el grafo es la memoria que sobrevive entre sesiones. Y si tenés que debuggear qué estaba "pensando" el modelo, el bundle de graft te da el contexto exacto que se le inyectó.

Que NO es Graft, y donde no aplica

Para no vender humo:

• No es un reemplazo de la búsqueda en el código. Si necesitás encontrar un símbolo específico, grep o LSP siguen siendo más rápidos que un round-trip al grafo. Graft es para entender sistemas, no para encontrar strings.
• No escala a 10 millones de líneas. El README recomienda graft para codebases de hasta ~500K líneas. Más allá, el grafo en sí se vuelve ruidoso y necesita jerarquías que el build no genera automáticamente todavía.
• No es gratis en tokens de build. graft init indexa todo el repo, llama al LLM para resumir cada nodo y enlazarlos. En un repo grande son varios minutos y un costo de API que puede ser de USD 5-20 la primera vez. Después, los rebuilds incrementales son baratos.
• No es mágico con código mal organizado. Si tu repo no tiene módulos claros, el grafo refleja el caos. Graft no estructura el código por vos — lo mapea.

Como probarlo sin comprometerte

El approach más sano es empezar por un repo tuyo chico-mediano y ver si los números se replican. Mi recomendación si querés probarlo ya:

1. Instalá y corré graft init --dry-run en un repo donde tengas tareas reales pendientes. Te lista todos los archivos que Graft tocaría sin escribir nada. Si la lista te parece razonable, seguí.
2. Probá push mode primero, que es el que mejores números da. Si notás que el agente gasta demasiado contexto en prompts cortos, pasate a pull mode.
3. Medí vos. Los números del README están sobre dos repos y 162 runs. En tu codebase, los números van a ser distintos. Lo que importa es la dirección (menos tokens, menos tiempo, igual o mejor correctness) y que el grafo siga siendo útil cuando lo abras como humano.
4. Commiteá el grafo en un branch aparte la primera vez. Cuando estés conforme con la calidad de los nodos y del auto-rebuild, mergeá a main.

Si venís de setups más pesados tipo Cloudflare OS o de governance empresarial, Graft te va a parecer chico. Pero para equipos de 1-10 devs que viven en Claude Code, es exactamente el tipo de capa fina que se nota en el pocket sin agregar vendor lock-in.

Conclusion: el contexto es la nueva prompt engineering

La conversación sobre coding agents estuvo dominada por dos ejes en 2026: el modelo (Opus 5, Muse Glimmer, Qwen 3.8) y la seguridad (permission fatigue, sandboxing, escapes). Graft propone un tercer eje: la calidad del contexto que le das al modelo importa más que el modelo mismo. Sus propios números lo muestran — 12 puntos de SWE-bench sin cambiar una línea del agente.

Es el ángulo que conecta lo que Opus 5 hace mejor con el costo de cada run: si podés bajar 42% los tokens manteniendo o subiendo la calidad, el cálculo económico de tener un coding agent en el loop cambia. Y si el grafo es commiteado y legible, el costo cognitivo de onboarding a un repo nuevo baja otro tanto.

No es la bala de plata. Pero es el primer proyecto open-source que trata el "mapa del repo" como artifact de primera clase en vez de side-effect del grep del modelo. Vale la pena probarlo en serio, aunque sea para tener el dato propio antes de opinar.