agent-usage-guard: cómo evitar que Claude Code agote tu límite de uso con subagentes

agent-usage-guard es un mod de Claude Code, con licencia MIT, que frena el fan-out de subagentes, los prompts con contexto pesado y los reintentos en bucle antes de que agoten tu límite de uso. Lee los porcentajes de la ventana de 5 horas y de la semanal que reporta Claude Code, y cuenta los agentes de todas las sesiones abiertas en tu máquina. Cuando se cruza un umbral, primero te pregunta; si nadie puede responder, se niega. La versión 1.1.0, publicada el 23 de octubre de 2026, agrega un modo de cierre: cuando una ventana del plan llega al 95 por ciento, cada sesión recibe la instrucción de terminar el paso en curso e informar qué queda pendiente.

https://github.com/rbartoli/agent-usage-guard

Actualización, 24 de octubre de 2026: al momento de publicar esta nota, el CHANGELOG del repositorio lista dos correcciones de seguridad todavía sin publicar (Unreleased). Las explicamos en la sección de seguridad.

¿Por qué Claude Code agota el límite de uso tan rápido?

Porque los costos se multiplican, no se suman. El autor identifica cuatro factores que se potencian entre sí: un contexto grande, bucles rápidos de herramientas, agentes en paralelo y reintentos a ciegas.

En el README cuenta la tarde que lo llevó a construir el guard. Le dio a Claude Code un prompt de investigación con esfuerzo máximo, y Claude Code lanzó 394 llamadas a subagentes, 341 de ellas al mismo tiempo. En diez minutos pasó 84 millones de tokens de contexto por la API y la sesión terminó con el mensaje Claude usage limit reached.

Son cifras del propio autor, tomadas de sus registros y no verificadas de forma independiente. Según el mismo relato, en sesenta días de registros tuvo 12 bloqueos. También enlaza reportes públicos parecidos: 339 subagentes a partir de un solo prompt, y la mitad de un plan Max semanal consumida por subagentes que lanzaban otros subagentes.

Cada regla del guard elimina uno de esos cuatro factores.

¿Qué es un mod de Claude Code?

Un mod es un tipo de plugin de Claude Code formado por manejadores de eventos en JavaScript o TypeScript que se ejecutan dentro de Claude Code. Esa es la diferencia con los hooks clásicos que se configuran en settings.json, que ejecutan un script externo. Como un mod vive en el mismo proceso, puede intervenir en un evento antes de que ocurra: retener una llamada a una herramienta mientras te hace una pregunta, reescribir un prompt o rechazar una acción.

Eso es justo lo que agent-usage-guard necesita. Su CHANGELOG explica que la versión anterior (0.2.5) estaba construida sobre hooks de configuración y solo podía aproximar lo que los mods exponen directamente: el contexto en vivo, los porcentajes de la ventana del plan y un evento que se puede rechazar antes de que arranque cada agente.

Los mods están activos por defecto desde Claude Code v2.1.287 en la terminal.

¿Cómo limita los subagentes de Claude Code y el contexto?

El guard actúa en tres momentos: antes de que arranque un agente, antes de que se envíe un prompt y antes de que se ejecute una llamada a una herramienta. Estos son sus valores por defecto según el README:

Área	Regla	Por defecto	Qué hace
Ventana del plan	Ventana así de llena	80%	pregunta antes de nuevos agentes
Ventana del plan	Ventana así de llena	95%	rechaza nuevos agentes
Ventana del plan	La ventana de 5 horas sube así de rápido	20 puntos / 10 min	pregunta
Agentes	Agentes corriendo a la vez, en todas las sesiones de la máquina	4	pregunta
Agentes	Agentes iniciados o reanudados cada 10 minutos	12	pregunta
Agentes	Tokens procesados por subagentes cada 10 minutos	10M	pregunta
Agentes	Subagentes que lanzan sus propios agentes	profundidad 1	rechaza
Contexto	Aviso único para que Claude acote el turno	300k tokens	agrega una nota
Contexto	Prompt que volvería a leer este contexto	500k tokens	pregunta: compactar y enviar, enviar igual o cancelar
Contexto	Llamadas a herramientas cada 10 min con este contexto	20 llamadas a 400k	pregunta
Contexto	Sesión pesada inactiva el tiempo suficiente para que expire su caché	150k tokens, 1 h inactiva	pregunta antes de reescribir la caché
Bucles	La misma llamada falla una y otra vez	3 fallos idénticos	rechaza el reintento idéntico
Bucles	Agentes rechazados en 10 minutos	5	pausa los lanzamientos 10 min

La regla de la sesión inactiva tiene que ver con la caché de prompts, que explicamos en detalle en Tu caché de 5 minutos no dura 5 minutos. Si todavía no usas subagentes, empieza por Sub-agents en Claude Code.

Dos decisiones de diseño importan en el uso diario:

• Una respuesta vale por un rato. Si permites algo, el guard no vuelve a preguntar hasta que la condición desaparece. Una ventana del plan queda permitida hasta que se reinicia, y los conteos de agentes quedan permitidos durante 10 minutos. El autor lo incorporó porque su versión anterior preguntó 136 veces en sesiones de contexto alto y la respuesta fue "sí" en 132.
• Sin una persona, rechaza. En claude -p, el Agent SDK o el modo dontAsk, rechaza y explica el motivo. Claude lee el rechazo como el resultado de la herramienta, así que puede esperar, agrupar el trabajo o detenerse. Los rechazos repetidos suben de tono, y el tercero le pide a Claude que termine el turno.

¿Qué hace el nuevo modo de cierre al 95 por ciento?

Según el CHANGELOG de la 1.1.0, cuando cualquier ventana del plan en la máquina llega al 95 por ciento, el siguiente prompt de cada sesión lleva una nota para Claude: termina el paso en curso, no empieces nada grande y cierra el turno con lo hecho y lo pendiente.

El autor explica por qué lo agregó. Los bloqueos que seguía viendo después de la 1.0 venían de muchas sesiones principales corriendo en paralelo, y eso no lo frenaba ninguna regla. Ahora, cuando llega el bloqueo, las encuentra en un punto limpio y no a mitad de un cambio. Una sesión inactiva también se entera de que otra sesión llenó la ventana. Cada sesión recibe el aviso una sola vez, y solo vuelve a recibirlo cuando la ventana baja del umbral, por ejemplo después de su reinicio.

La versión 1.1.1, publicada el mismo día, corrige un doble conteo: desde Claude Code 2.1.299, reanudar un subagente con SendMessage contaba como dos inicios. También hace que /agent-guard status muestre qué versión está corriendo.

¿Cómo se instala agent-usage-guard en Claude Code?

Dentro de Claude Code v2.1.287 o posterior, ejecuta:

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

Después ejecuta /agent-guard para ver lo que ve el guard.

Estos son los comandos que vas a usar:

/agent-guard [status]                          what the guard sees right now
/agent-guard allow [agents|context] [minutes]  lift its limits for this session (default: all, 10 min)
/agent-guard pause [minutes]                   the same as allow, for every limit
/agent-guard resume                            end an allow early
/agent-guard report [days]                     what it did on this machine (default: 7 days)

/agent-guard se ejecuta sin iniciar un turno del modelo, así que Claude nunca ve una anulación y no puede tomarla como permiso.

¿Cómo se ajustan los umbrales?

Con variables de entorno, o dentro de env en ~/.claude/settings.json. Algunas de las más útiles:

• AGENT_GUARD_AGENT_MAX: agentes corriendo a la vez en la máquina (por defecto 4).
• AGENT_GUARD_LIMIT_ASK_PERCENT y AGENT_GUARD_LIMIT_DENY_PERCENT: umbrales para preguntar y para rechazar (80 y 95).
• AGENT_GUARD_CONTEXT_HARD: contexto a partir del cual un prompt pregunta antes de enviarse (500000).
• AGENT_GUARD=0: apaga el guard sin desinstalarlo.

El README documenta 22 variables en total.

¿Funciona con una API key?

Sí, con dos diferencias. Las sesiones con API key no reportan los porcentajes de la ventana del plan, así que solo se aplican los presupuestos de tokens y de conteo de agentes. Además, la caché de prompts dura cinco minutos en lugar de una hora, por lo que el README recomienda AGENT_GUARD_DORMANT_SECONDS=300. Lo mismo vale si usas uso adicional (extra usage).

¿Qué no puede ver?

El README es explícito sobre sus puntos ciegos, verificados contra Claude Code v2.1.295:

• No cuenta sesiones en otras máquinas, porque los registros compartidos viven en el almacén de mods de cada equipo.
• No ve a los compañeros de equipo (teammates) que corren en su propio panel de terminal, porque corren en otros procesos.
• Los forks de /subtask, y todo lo que arranca sin el evento agent.spawn, se cuentan pero nunca se retienen.
• No corre en una sesión WSL de la app de escritorio.

Los límites nativos de Claude Code siguen vigentes: una sesión admite hasta 20 subagentes concurrentes y tres niveles de anidamiento, pero no hay límite al total de agentes que una sesión lanza. Los valores por defecto del guard son más estrictos y abarcan todas las sesiones.

¿Es seguro instalar un mod de Claude Code?

Un mod corre con tus permisos y no está aislado en un sandbox. La documentación de Anthropic lo dice sin rodeos: un mod puede leer tus archivos, tus variables de entorno y tu sesión. Según las notas de privacidad del autor, el guard son unas 2.400 líneas de TypeScript sin dependencias, no hace peticiones de red ni inicia procesos, y guarda conteos y rangos aproximados, nunca el texto de los prompts ni las entradas de las herramientas. Puedes revisar qué APIs usa con claude plugin validate . antes de instalarlo.

Al momento de publicar esta nota, el CHANGELOG lista dos correcciones de una revisión de seguridad del 24 de octubre de 2026 que todavía no forman parte de una versión publicada:

• Hasta que salga esa corrección, cualquier otro plugin instalado podía ejecutar /agent-guard allow y levantar todos los límites hasta por ocho horas.
• Una pregunta que terminaba sin respuesta podía dejar arrancar un agente; con la corrección cuenta como "no".

Antes de confiar en el guard en sesiones con otros mods instalados, comprueba que tu versión incluya ambas correcciones. Para revisar si cualquier mod es seguro, mira cómo probamos ModVet, el escáner que revisa un plugin antes de instalarlo.

¿agent-usage-guard o Claude HUD?

Resuelven problemas distintos y funcionan bien juntos. Claude HUD te muestra qué está haciendo Claude Code y cuánto te cuesta. agent-usage-guard le pone un techo a ese costo y lo aplica antes de que se gaste.

---

¿Y tú? ¿Cuántos subagentes dejas correr en paralelo en Claude Code antes de empezar a preocuparte por el límite?

Comenta abajo o, si este artículo te llegó por correo, responde directamente al email: tu respuesta se publica aquí.

Relacionado: Claude HUD: El Plugin que te Dice Exactamente Qué Está Haciendo Claude Code (y Cuánto te Está Costando)