Repolode
Enviar
rbartoli

rbartoli/agent-usage-guard

Un mod de Claude Code que frena la expansión de subagentes, los prompts con mucho contexto y los ciclos de reintentos antes de que consuman la ventana de uso de tu plan.

Ver en GitHub
Estrellas
94
Forks
5
Issues abiertos
0
Último commit
anteayer

¿Qué es?

agent-usage-guard es un mod para Claude Code que verifica cada inicio de agente, prompt y llamada a herramientas antes de ejecutarlos. Lee los porcentajes de uso de las ventanas de 5 horas y semanal que informa tu plan, y cuenta los agentes activos y recientes en todas las sesiones de Claude Code de la máquina. Cuando se alcanza un límite, pregunta mediante el cuadro de diálogo de Claude Code o, si nadie puede responder —como ocurre con claude -p o Agent SDK—, rechaza la acción y explica el motivo.

Las reglas predeterminadas limitan a cuatro los agentes simultáneos, a doce los inicios cada diez minutos y a diez millones los tokens de subagentes por ventana. También detectan contextos grandes, como prompts que volverían a leer 500k tokens, o ráfagas de llamadas a herramientas con mucho contexto. Una aprobación sigue vigente hasta que se resuelve la condición o vence el plazo, así que no se repite la misma pregunta en cada llamada. El guard falla de forma abierta: si uno de sus hooks da error, el evento continúa.

Se ejecuta localmente, sin acceso a la red ni procesos en segundo plano. Almacena conteos y categorías generales, no el texto de los prompts, las entradas de las herramientas ni las salidas del modelo. El comando /agent-guard report resume las acciones en las que intervino.

Funciones clave

  • 01Pregunta antes de iniciar agentes cuando el uso de la ventana de 5 horas o semanal del plan supera los umbrales definidos.
  • 02Limita los agentes simultáneos, los inicios de agentes y los tokens de subagentes en todas las sesiones de la máquina.
  • 03Pregunta antes de ejecutar prompts que volverían a leer contextos grandes y limita las ráfagas de llamadas a herramientas cuando hay mucho contexto.
  • 04Rechaza los reintentos idénticos de herramientas tras varios fallos.
  • 05Se ejecuta localmente, sin acceso a la red, y no almacena el contenido de prompts ni de herramientas.
  • 06/agent-guard report resume las intervenciones realizadas.

Casos de uso

  • Ejecutar investigaciones en paralelo o flujos de trabajo multiagente en Claude Code sin agotar la ventana de uso de cinco horas.
  • Crear scripts con claude -p o trabajos de Agent SDK que rechacen una expansión excesiva de agentes en vez de llegar a un bloqueo.
  • Evitar que un ciclo de reintentos consuma el contexto de una sesión prolongada.

Inicio rápido

  1. 1

    Añade el marketplace dentro de Claude Code

    /plugin marketplace add rbartoli/agent-usage-guard
  2. 2

    Instala el plugin

    /plugin install agent-usage-guard@agent-usage-guard
  3. 3

    Vuelve a cargar los plugins

    /reload-plugins
  4. 4

    Ejecuta el comando status para ver qué detecta el guard

    /agent-guard

Antes de usarlo

  • Se requiere Claude Code v2.1.287 o posterior.
  • Algunas rutas no están cubiertas, como las bifurcaciones de /subtask y los compañeros que ejecutan sus procesos en sus propias pestañas del terminal.
  • Las lecturas de la ventana Plan no están disponibles en sesiones con una clave de API.
  • No se ejecuta en una sesión WSL de la aplicación Desktop.

En colecciones

Herramientas, skills y plugins para Claude CodeFrameworks y apps de agentes de IA open source

Temas

#ai-agents#claude-code#rate-limiting#guardrails#subagents#developer-tools#claude-code-mod#claude-code-plugin#typescript#usage-limits

Preguntas frecuentes

¿Qué es agent-usage-guard?
Un mod de Claude Code que frena la expansión de subagentes, los prompts con mucho contexto y los ciclos de reintentos antes de que consuman la ventana de uso de tu plan. agent-usage-guard es un mod para Claude Code que verifica cada inicio de agente, prompt y llamada a herramientas antes de ejecutarlos. Lee los porcentajes de uso de las ventanas de 5 horas y semanal que informa tu plan, y cuenta los agentes activos y recientes en todas las sesiones de Claude Code de la máquina. Cuando se alcanza un límite, pregunta mediante el cuadro de diálogo de Claude Code o, si nadie puede responder —como ocurre con claude -p o Agent SDK—, rechaza la acción y explica el motivo.
¿agent-usage-guard es gratuito? ¿Qué licencia tiene?
agent-usage-guard es open source bajo la licencia MIT. Revisa los términos de la licencia antes de usarlo en productos comerciales.
¿agent-usage-guard sigue mantenido?
Mantenimiento activo. El último commit de agent-usage-guard fue el 6 nov 2026.
¿Para qué puedo usar agent-usage-guard?
Ejecutar investigaciones en paralelo o flujos de trabajo multiagente en Claude Code sin agotar la ventana de uso de cinco horas. Crear scripts con claude -p o trabajos de Agent SDK que rechacen una expansión excesiva de agentes en vez de llegar a un bloqueo. Evitar que un ciclo de reintentos consuma el contexto de una sesión prolongada.
¿Cómo se instala agent-usage-guard?
Añade el marketplace dentro de Claude Code: /plugin marketplace add rbartoli/agent-usage-guard Instala el plugin: /plugin install agent-usage-guard@agent-usage-guard Vuelve a cargar los plugins: /reload-plugins Ejecuta el comando status para ver qué detecta el guard: /agent-guard
¿Dónde consigo agent-usage-guard?
El código fuente y las instrucciones de instalación están en GitHub: https://github.com/rbartoli/agent-usage-guard

Resumen generado por IA a partir del README del proyecto. Las estadísticas de GitHub se actualizan a diario.

Proyectos relacionados