agent-usage-guard, el mod que cuida tu cuota de Claude Code

Que es agent-usage-guard y por que existe

394 llamadas a subagentes, 341 corriendo a la vez y 84 millones de tokens de contexto en diez minutos. Ese es el episodio que el desarrollador rbartoli documenta como origen de agent-usage-guard, un mod de codigo abierto (licencia MIT, unas 2.400 lineas de TypeScript sin dependencias) que se instala dentro de Claude Code y frena el gasto descontrolado antes de que ocurra.

El problema no es anecdótico. Segun el propio autor, 60 dias de sus registros contienen 12 bloqueos por limite de uso y 166 ventanas de diez minutos con rafagas de agentes. El patron se multiplica: contexto grande por bucles rapidos de herramientas por agentes en paralelo por reintentos a ciegas. Cada proteccion del mod elimina uno de esos factores.

La herramienta llega en un momento en que el ecosistema de extensiones de Claude Code explota. Anthropic abrio un marketplace de Claude con mas de 2.000 plugins y conectores de companias como Atlassian, Google, Microsoft, Notion y Salesforce, segun BleepingComputer. Con ese volumen, la pregunta deja de ser que instalo y pasa a ser que me esta consumiendo la cuota.

Leíste lo que hace la IA. ¿Y en tu negocio?

En CAR, dueños de empresa arman en 7 días su primer sistema funcionando: que ningún cliente se les escape, o que el informe del lunes salga solo. Con otros emprendedores al lado.

👥 Probar 7 días

Como funciona: actua antes del gasto, no despues

La diferencia clave con un panel de metricas es el momento de la intervencion. agent-usage-guard decide antes de que arranque un agente, antes de que se envie un prompt y antes de que corra una llamada a herramienta. No te avisa de que ya gastaste: te pregunta si quieres gastar.

Consciente del plan. Lee los porcentajes de la ventana de 5 horas y de la semana que reporta Claude Code, y reserva el final de la ventana para ti.
Una respuesta cubre un rato. Una aprobacion levanta su condicion hasta que se limpia o expira, asi que la misma pregunta no vuelve llamada tras llamada.
Local y con minima huella de datos. Sin red y sin procesos externos. Guarda conteos y rangos gruesos, nunca el texto de tus prompts, las entradas de herramientas ni la salida del modelo.
Falla abierto. Si uno de sus hooks falla, el evento sigue adelante: un guard roto nunca rompe tu sesion.

Cuando estas frente al teclado, la pregunta aparece en el propio dialogo de Claude Code y la llamada espera tu respuesta. Cuando nadie puede responder, en claude -p, el Agent SDK o el modo dontAsk, el guard rechaza y le explica a Claude por que, para que el modelo espere, agrupe el trabajo o se detenga.

Los limites por defecto que trae el mod

Los valores por defecto son deliberadamente mas estrictos que los nativos de Claude Code. Estos son los que mas impactan el dia a dia:

80% de la ventana del plan: los agentes nuevos piden aprobacion.
95%: los agentes nuevos se rechazan directamente.
4 agentes corriendo a la vez en toda la maquina, no por sesion.
12 arranques o reanudaciones de agentes cada 10 minutos.
10 millones de tokens de subagentes cada 10 minutos.
Profundidad 1: un subagente no puede lanzar sus propios agentes.
3 fallos identicos consecutivos: se rechaza el reintento identico.
5 rechazos de agentes en 10 minutos: se pausan los arranques por 10 minutos.

Todo es configurable por variables de entorno o en ~/.claude/settings.json, y /agent-guard report muestra que hizo en los ultimos dias. El mod corre en claude en una terminal, en la pestana Code de la app de escritorio, en claude -p y en el Agent SDK.

Cuanto cuesta realmente un enjambre de subagentes

Aqui esta la parte que duele. XDA Developers documento el caso de un desarrollador que repartio su trabajo entre cinco subagentes de Claude Code y agoto su ventana de uso en menos de una hora. El motivo: Claude Code reprocesa toda la conversacion en cada turno, system prompt, mensajes previos, definiciones de herramientas y salidas anteriores incluidas, asi que una sesion de apenas 30 mensajes puede exigir alrededor de 90.000 tokens de procesamiento.

El efecto se compone. Tres agentes que devuelven un resumen de 2.000 tokens cada uno suman 6.000 tokens al contexto del padre en un solo ciclo; repite eso diez veces y el orquestador acumula unos 60.000 tokens solo en resumenes, sin contar la tarea original ni el historial.

Y la tendencia va en la direccion contraria a la contencion. Anthropic reporto el 24 de septiembre de 2026 que, entre marzo y septiembre de ese ano, el contexto por request crecio 2,6 veces, el modelo trabaja 3,3 veces mas tiempo por prompt y hace mas de 40% mas llamadas por prompt, segun Unite.ai. La relacion de tokens de entrada a salida paso de 189:1 a 324:1.

La buena noticia es que el costo por token bajo: Anthropic recorto 20% los precios de entrada y salida y 60% el de lectura de cache. Segun el analisis de Addy Osmani recogido por Unite.ai, Opus 5.5 lista a US$4 por millon de tokens de entrada, US$20 por millon de salida y US$0,20 por millon de lecturas de cache. Por eso proteger la cache importa tanto: en planes Pro, Max o Team, el precio mas bajo de Opus 5.5 se traslada a los limites del plan, que rinden alrededor de 25% mas.

Anthropic tambien duplico los limites de sesion de 5 horas para los planes pagos, aunque los topes semanales no cambiaron, segun Geeky Gadgets. Mas cuota no cambia el patron de consumo: lo hace mas caro de agotar.

Que significa esto para tu startup

Si tu equipo usa Claude Code para desarrollar, la cuota es un recurso de produccion, no un detalle de facturacion. Un bloqueo de ventana a mitad de un sprint es tiempo de ingenieria perdido, y en un equipo pequeno eso se siente igual que una caida de servicio.

Tres acciones concretas:

Mide antes de optimizar. Corre /usage dentro de Claude Code para ver que proporcion de la sesion se sirve desde cache. Si el porcentaje es bajo, el problema no es el volumen de trabajo sino la forma en que lo estas ejecutando.
Elige el modelo al inicio de la sesion, no a mitad. Cambiar de modelo en medio de una conversacion rompe la cache y te obliga a reprocesar contexto que ya habias pagado. Lo mismo aplica a la compactacion: hazla antes de levantarte de la mesa, no despues.
Si usas API key o proveedor cloud, activa la cache de una hora. Por defecto, la conversacion principal en una suscripcion dentro del plan dura una hora, pero con API key, creditos de uso o proveedores cloud la cache dura cinco minutos. El ajuste promptCacheTtl o la variable CLAUDE_CODE_PROMPT_CACHE_TTL seleccionan la vida larga y requieren Claude Code v2.1.242 o posterior. Si trabajas con API key, ajusta tambien AGENT_GUARD_DORMANT_SECONDS=300 para que los supuestos del guard coincidan con los tuyos.

Como instalarlo en cinco minutos

Requiere Claude Code v2.1.287 o posterior. Dentro de Claude Code:

/plugin marketplace add rbartoli/agent-usage-guard
/plugin install agent-usage-guard@agent-usage-guard
/reload-plugins

Despues, /agent-guard muestra que esta viendo en ese momento. Los mods vienen activados por defecto y el overview lista los ajustes para desactivarlos. Para apagarlo sin desinstalarlo, AGENT_GUARD=0. Y si el guard te pregunta, puedes responderle con texto: las palabras escritas llegan a Claude, asi que puedes contestar que use agentes mas livianos en lugar de los actuales.

Lo que el mod no puede proteger

Conviene ser honesto con los limites. Los agentes que corren en sus propias terminales no son visibles, porque sus bucles viven en otros procesos. Las sesiones en otras maquinas no se cuentan: los registros entre sesiones viven en el store local de esa maquina. Los agentes internos de Claude Code, como las sugerencias de prompt y la compactacion, no se cuentan, y las herramientas que ejecuta la propia API no son retenibles porque no disparan evento de herramienta.

Tambien hay una capa nativa que sigue siendo el muro exterior: Claude Code limita a 20 subagentes concurrentes por sesion y tres niveles de anidamiento, pero no tiene tope en el numero total de agentes que arranca una sesion. Ahi es exactamente donde un guard externo aporta algo que el producto no trae.

Y como todo mod corre dentro de Claude Code con tus permisos, el propio autor recomienda leer que puede alcanzar un mod antes de instalarlo. En este caso, claude plugin validate . lista cada API que llama y cada variable de entorno que lee: no hace requests de red, no arranca procesos, no cambia tus permisos ni escribe settings.

Conclusion

agent-usage-guard no es una herramienta de ahorro: es un control de flujo. La leccion de fondo es que los agentes en paralelo cambiaron el perfil de consumo de Claude Code, con mas contexto, mas llamadas y mas tiempo por prompt, y las cuotas no crecieron al mismo ritmo. Un guard que pregunta antes de gastar, con valores por defecto conservadores y la posibilidad de responderle con instrucciones concretas, es una forma barata de convertir un bloqueo de ventana en una decision consciente.

Fuentes

¿te gustó o sirvió lo que leíste?, Por favor, comparte.

WhatsApp X LinkedIn

Leíste lo que hace la IA. ¿Y en tu negocio?

En CAR, dueños de empresa arman en 7 días su primer sistema funcionando: que ningún cliente se les escape, o que el informe del lunes salga solo. Con otros emprendedores al lado.

👥 Probar 7 días