Cómo Reducir los Costos de Tokens de Agentes en Flujos de Trabajo CLI

Soy Dora. El mes pasado ejecuté un único npm test a través de Claude Code y observé cómo la sesión consumió aproximadamente 12.000 tokens de entrada antes de que el agente me respondiera una sola palabra. La salida del test tenía 400 líneas. Quizás 30 de ellas importaban. El resto —advertencias de deprecación, ruido de dependencias, los puntos de progreso de Jest— todo fue directamente al contexto del modelo. Pagué por cada byte.

Fue entonces cuando dejé de tratar los tokens como “algo que gestiona el modelo” y empecé a tratarlos como un presupuesto que estaba perdiendo activamente. Si ejecutas flujos de trabajo CLI agénticos en Claude Code, Gemini CLI o algo similar, esta es probablemente tu mayor línea de costos — y la solución no es un modelo mejor, sino mejores hábitos. La propia documentación de gestión de costos de Anthropic lo dice claramente: los costos de tokens escalan con el tamaño del contexto, y la mayor parte de la optimización ocurre antes de que el modelo vea los datos. Este artículo trata sobre cómo reducir los costos de tokens del agente en flujos de trabajo CLI sin perder la señal de depuración que necesitas.

Dónde Desperdician Tokens los Flujos de Trabajo CLI

Antes de arreglar nada, tuve que descubrir dónde estaban las fugas. Dos patrones se destacaron, y aparecen en casi todos los flujos de trabajo CLI que he auditado desde entonces.

Comandos Verbosos y Salida Irrelevante

Los comandos de terminal fueron diseñados para humanos que hojean una pantalla, no para LLMs que leen byte a byte. git status imprime códigos ANSI que el modelo no necesita. npm install vuelca mil líneas del árbol de dependencias que el modelo ya conoce. next build hace eco de su propio progreso durante quince segundos. Nada de esto se gana su lugar en la ventana de contexto.

Los números son peores de lo que parecen en papel. Una sola ejecución de cargo test en un proyecto Rust mediano puede producir entre 8.000 y 15.000 tokens de salida. La mayor parte es ruido de compilación. Cuando el agente lo lee todo para encontrar una única aserción fallida, has pagado tarifas de nivel Opus por el privilegio de transmitir un registro de compilación.

Esta es también la razón por la que existen proyectos comunitarios como rtk y tokf — se ubican entre el shell y el agente, filtran el texto repetitivo antes de que llegue al contexto, y reportan ahorros en el rango del 70–90% en comandos comunes. Uses o no un envoltorio, el principio se mantiene: la salida de terminal en bruto no es datos listos para LLM.

Arrastre de Contexto y Lecturas Repetidas

La segunda fuga es más sutil. Cada llamada a herramienta que hace el agente —lectura de archivo, grep, comando bash— permanece en el historial de conversación. Para el turno diez, el modelo está reprocesando nueve turnos de salidas obsoletas en cada solicitud. El propio postmortem de abril de Anthropic sobre problemas de calidad de Claude Code describe exactamente esta dinámica: un error de caché provocó que el historial de pensamiento se acumulara entre turnos, y el uso de tokens se infló 10–20x antes de que alguien lo notara. Incluso sin errores, este es el comportamiento predeterminado. Las sesiones largas son sesiones costosas.

Revisé una de mis propias sesiones de hace una semana. El agente había leído el mismo package.json cuatro veces. Ninguna de esas relecturas añadió información — el archivo no había cambiado. Eran solo artefactos del agente que no sabía lo que ya sabía.

Paso 1: Comprimir las Salidas Ruidosas

La corrección más barata, por un amplio margen, es evitar que la basura entre al contexto desde el principio. Tres reglas, en este orden:

Filtra en la fuente, no después. En lugar de npm test, el agente ejecuta npm test —silent 2>&1 | grep -E “(FAIL|PASS|Error)”. En lugar de git status, ejecuta git status —short. En lugar de cargo build, ejecuta cargo build —quiet 2>&1 | tail -20. Nada de esto es ingenioso. Es simplemente disciplina. El agente obtiene el test fallido, los archivos modificados, el error real — nada más.

Limita la salida de herramientas a nivel del harness. Claude Code te permite establecer un tamaño máximo de salida de herramienta. Bajé el mío a 8.000 caracteres por llamada. Cuando un comando lo excede, el agente recibe un aviso de truncamiento y decide si refinar la consulta. Esta única configuración me ahorró más tokens que todos los demás cambios combinados.

Usa un proxy CLI cuando la herramienta upstream no se calla. Algunos comandos no tienen ningún indicador de silencio que valga la pena usar — next build, webpack, cualquier cosa basada en Java. Para estos, un envoltorio que elimine el texto repetitivo conocido vale el tiempo de configuración. Las herramientas de la familia rtk/tokf manejan esto genéricamente; también puedes escribir una función bash de 30 líneas para los tres comandos que más te molestan.

Aquí hay una compensación real. La compresión agresiva puede ocultar la señal de depuración. Cuando una compilación falla por una razón que el filtro elimina —una advertencia de deprecación que se convirtió en un error, un problema de configuración oscuro enterrado en la línea 847— el agente obtiene una imagen más corta y menos útil. Me ha pasado dos veces. Ambas veces la solución fue aflojar una regla del filtro, no abandonar la estrategia.

Paso 2: Limitar el Contexto Antes de que Llegue al Modelo

El filtrado de salida maneja los tokens nuevos que entran en cada turno. La disciplina de contexto maneja los tokens acumulados que ya están dentro de la sesión. Problemas diferentes.

Los dos comandos que importan, ambos directamente de las mejores prácticas de Claude Code de Anthropic, son /clear y /compact. /clear restablece la sesión completamente — útil cuando se cambia a una tarea no relacionada. /compact resume el historial anterior preservando las decisiones clave y el estado actual — útil cuando la tarea continúa pero la exploración inicial ya no es relevante. Claude Code se compacta automáticamente cuando se acerca a los límites de contexto, pero esperar ese disparador suele ser demasiado tarde. Para entonces ya has pagado la tarifa inflada durante varios turnos.

Mi hábito actual: ejecuto /compact en cada límite de tarea natural, con una instrucción como /compact Focus on the failing test and the recent file edits. La instrucción importa. Sin ella, la compactación resume todo de manera aproximada. Con ella, el agente conserva las partes que importan para la siguiente fase.

Para agentes basados en API (no la suscripción CLI), la documentación de edición de contexto de Anthropic describe un mecanismo más estricto: clear_tool_uses_20250919 borra automáticamente los resultados de herramientas antiguos una vez que el contexto supera un umbral. El agente retiene la conversación pero pierde las salidas brutas que ya procesó. Para tareas agénticas de largo horizonte, este es el predeterminado correcto.

Una cosa que señalaría: un CLAUDE.md inflado es un impuesto permanente. Se carga en cada turno, en cada sesión, para siempre. Recorté el mío de ~280 líneas a ~90. El recuento de tokens por turno bajó notablemente y el comportamiento del agente no cambió de ninguna manera que pudiera medir.

Paso 3: Rediseñar las Herramientas del Agente para Menor Desperdicio

Los primeros dos pasos son tácticos. Este es estructural, y es donde viven los ahorros duraderos.

Diseña herramientas que emitan salida amigable para LLM. La CLI Spec impulsada por la comunidad hace este argumento mejor que yo: los comandos diseñados para agentes deben soportar un indicador —output, separar los datos (stdout) de los diagnósticos (stderr), y proporcionar paginación en lugar de volcar JSON ilimitado. Si estás construyendo CLIs internas que tus agentes llamarán, sigue esa especificación. Si usas CLIs externas que no lo hacen, envuélvelas.

Prefiere herramientas estrechas sobre amplias. Una función git_status_summary que devuelve tres campos estructurados supera dejar que el agente ejecute git status en bruto y analice la salida. Cada capa de análisis que el modelo tiene que hacer es una capa donde se queman tokens en traducción en lugar de razonamiento. Convertí cuatro de mis comandos más usados en envolturas delgadas de Python que devuelven JSON. El uso de tokens de ida y vuelta en esas operaciones cayó aproximadamente un 60%.

Usa subagentes para trabajo de lectura intensiva. La función de subagentes de Claude Code ejecuta un contexto separado para tareas como “escanea el repositorio y resume el flujo de autenticación”. Los hallazgos regresan como un resumen compacto — no los 40 archivos que el subagente realmente leyó. La conversación principal nunca ve los datos en bruto. Para tareas de exploración intensiva, esta es la mayor ganancia estructural disponible.

Adapta el modelo al trabajo. Opus 4.7 es impresionante y costoso. La mayor parte del trabajo CLI — ediciones de archivos, correcciones de tests, refactorizaciones rutinarias — funciona bien con Sonnet, a aproximadamente el 40% del costo por token de Opus. Vale la pena saber: el nuevo tokenizador de Opus 4.7 puede producir hasta un 35% más de tokens para texto idéntico en comparación con modelos anteriores, lo que amplifica la brecha de costos.

La advertencia honesta: mide antes de optimizar, luego mide después. Establecí una línea base con /cost (API) o /usage (suscripción) durante una semana antes de cambiar nada, luego volví a medir después de cada cambio. Dos de mis “optimizaciones” resultaron no hacer nada medible. Sin una línea base, solo estás adivinando.

Preguntas Frecuentes

¿Por qué los flujos de trabajo de terminal consumen tantos tokens?

Porque la salida de terminal fue diseñada para humanos, y los agentes pagan byte a byte. Un comando de compilación típico emite miles de líneas de progreso, advertencias y texto repetitivo que el modelo no necesita. Combina eso con un historial de conversación que nunca se reinicia y resultados de herramientas que se acumulan entre turnos, y obtienes sesiones que agotan los presupuestos de contexto antes de que el trabajo real comience.

¿Cuánto puede ayudar la compresión de salida?

En mis mediciones, el filtrado a nivel de comando más los límites de salida redujeron los tokens de entrada por turno en un 40–60% en ejecuciones de tests, compilaciones y operaciones de git. Los envoltores comunitarios como rtk reportan reducciones del 80–90% en comandos específicos, aunque esos números asumen la peor salida verbosa. Las ganancias reales dependen de qué comandos ejecuta más tu agente. Audita los cinco principales, corrígelos, y la mayor parte de los ahorros aparece de inmediato.

¿Qué deberían optimizar primero los equipos?

En este orden: límites de salida de herramientas, disciplina con /clear y /compact, selección de modelo. Los límites de salida son un cambio de configuración único sin costo continuo. La higiene de sesión es un hábito, pero es gratuita una vez que la tienes. La selección de modelo es la ganancia más fácil de pasar por alto — ejecutar todo en Opus cuando la mayoría de las tareas funcionan bien en Sonnet es una fuga silenciosa y grande.

¿Cuándo perjudica la optimización de tokens la calidad de depuración?

Cuando comprimes más allá del punto donde el agente puede ver qué falló. Un stack trace truncado, una advertencia de deprecación filtrada, un indicador —quiet que oculta el error real — todo esto me ha costado tiempo real. El patrón que sigo: comprime agresivamente en comandos rutinarios (git status, npm install, ejecuciones de tests exitosas), mantén la salida verbosa para operaciones conocidas como fallidas o desconocidas. Si te encuentras volviendo a ejecutar un comando sin filtros para depurar, el filtro estaba mal, no la estrategia.

Conclusión

Los costos de tokens en los flujos de trabajo CLI no son un problema del modelo. Son un problema de plomería. La mayor parte del gasto desaparece en la brecha entre lo que emiten los comandos de terminal y lo que el modelo realmente necesita para razonar — y esa brecha es solucionable con filtrado de salida, disciplina de contexto y herramientas que respeten al agente del otro lado.

Llevo aproximadamente seis semanas ejecutando la configuración anterior. El consumo diario de tokens en Claude Code ha bajado aproximadamente un 55%, la latencia del agente mejoró como efecto secundario de contextos más pequeños, y el flujo de trabajo se siente menos ruidoso para depurar. Ninguno de esos números es universal — tu línea base y tus cinco comandos principales se verán diferentes. Pero el patrón se mantiene: controla lo que entra al contexto, controla lo que permanece en el contexto, y deja que el modelo gaste su presupuesto en razonar en lugar de leer registros de compilación.

Ahí es donde terminan mis datos. La capa de compresión sigue evolucionando, y los cambios en el tokenizador de Anthropic significan que estos números tienen una vida útil. Vale la pena volver a establecer la línea base cada trimestre.

Publicaciones anteriores:

• ¿Qué es la Eficiencia de Tokens RTK?
• Patrones y Errores en el Cableado de Herramientas de Flujos de Trabajo Agénticos
• MCP en Producción: Flujos de Trabajo del Protocolo de Contexto de Modelo
• Arquitectura del Harness de Agente de Claude Code
• Claude Code vs Cursor 2026