agent-usage-guard: control de gasto en Claude Code

Fuentes: agent-usage-guard: a Claude Code mod to control spending

agent-usage-guard es una extensión (mod) para Claude Code diseñada para prevenir el agotamiento de la ventana de uso de la plataforma. Su función principal es detener el despliegue de agentes subagentes, el uso de contextos pesados y los bucles de reintentos antes de que se consuma el límite de tokens asignado, evitando así bloqueos de sesión. La herramienta opera de forma proactiva, evaluando las condiciones de uso en tiempo real antes de iniciar cada acción o llamada de herramienta, y solicita aprobación al usuario a través del diálogo nativo de la interfaz de Claude Code.

El sistema es consciente del plan de uso, leyendo los porcentajes de consumo de la ventana de cinco horas y la semanal. Implementa un mecanismo de 'una sola respuesta' para evitar que el usuario sea consultado repetidamente por la misma condición. Está diseñado para ser local y minimalista en privacidad, almacenando únicamente contadores y buckets de uso sin procesar texto de prompts ni entradas de herramientas. En caso de fallo en uno de sus componentes, el sistema permite que la sesión continúe (fail open), excepto cuando un agente no puede ser evaluado a tiempo, lo que provoca su denegación.

La herramienta incluye comandos específicos para gestionar el estado, como /agent-guard status, /agent-guard allow y /agent-guard report. Los parámetros por defecto limitan el número de agentes activos simultáneos, el volumen de tokens procesados por subagentes y la profundidad de las jerarquías de agentes. Esta solución es relevante para usuarios que realizan tareas de investigación complejas o sistemas multiagente, donde el consumo de recursos puede escalar rápidamente, como se documenta en casos de uso donde un solo prompt generó cientos de llamadas de subagentes y consumió la mayoría de los tokens de un plan semanal.