agent-usage-guard é um mod de Claude Code, com licença MIT, que freia o fan-out de subagentes, os prompts com contexto pesado e os reintentos em loop antes de que esgotem seu limite de uso. Lê os percentuais da janela de 5 horas e da semanal que o Claude Code reporta, e conta os agentes de todas as sessões abertas na sua máquina. Quando um limite é ultrapassado, primeiro te pergunta; se ninguém pode responder, se recusa. A versão 1.1.0, publicada em 23 de outubro de 2026, adiciona um modo de encerramento: quando uma janela do plano chega a 95 por cento, cada sessão recebe a instrução de terminar o passo em curso e informar o que fica pendente.
Atualização, 24 de outubro de 2026: no momento de publicar esta nota, o CHANGELOG do repositório lista duas correções de segurança ainda não publicadas (Unreleased). Explicamos na seção de segurança.
Por que Claude Code esgota o limite de uso tão rápido?
Porque os custos se multiplicam, não se somam. O autor identifica quatro fatores que se potencializam entre si: um contexto grande, loops rápidos de ferramentas, agentes em paralelo e reintentos às cegas.
No README conta a tarde que o levou a construir o guard. Deu ao Claude Code um prompt de pesquisa com esforço máximo, e Claude Code lançou 394 chamadas a subagentes, 341 delas ao mesmo tempo. Em dez minutos passou 84 milhões de tokens de contexto pela API e a sessão terminou com a mensagem Claude usage limit reached.
São cifras do próprio autor, tiradas de seus registros e não verificadas de forma independente. Segundo o mesmo relato, em sessenta dias de registros teve 12 bloqueios. Também vincula relatórios públicos parecidos: 339 subagentes a partir de um único prompt, e metade de um plano Max semanal consumida por subagentes que lançavam outros subagentes.
Cada regra do guard elimina um desses quatro fatores.
O que é um mod de Claude Code?
Um mod é um tipo de plugin de Claude Code formado por manipuladores de eventos em JavaScript ou TypeScript que se executam dentro de Claude Code. Essa é a diferença com os hooks clássicos que se configuram em settings.json, que executam um script externo. Como um mod vive no mesmo processo, pode intervir em um evento antes de que ocorra: reter uma chamada a uma ferramenta enquanto te faz uma pergunta, reescrever um prompt ou rejeitar uma ação.
Isso é exatamente o que agent-usage-guard precisa. Seu CHANGELOG explica que a versão anterior (0.2.5) era construída sobre hooks de configuração e só podia aproximar o que os mods expõem diretamente: o contexto em vivo, os percentuais da janela do plano e um evento que pode ser rejeitado antes de que arranque cada agente.
Os mods estão ativos por padrão desde Claude Code v2.1.287 no terminal.
Como limita os subagentes de Claude Code e o contexto?
O guard atua em três momentos: antes de que arranque um agente, antes de que se envie um prompt e antes de que se execute uma chamada a uma ferramenta. Estes são seus valores por padrão segundo o README:
| Área | Regra | Por padrão | O que faz |
|---|---|---|---|
| Janela do plano | Janela assim de cheia | 80% | pergunta antes de novos agentes |
| Janela do plano | Janela assim de cheia | 95% | rejeita novos agentes |
| Janela do plano | A janela de 5 horas sobe assim de rápido | 20 pontos / 10 min | pergunta |
| Agentes | Agentes correndo ao mesmo tempo, em todas as sessões da máquina | 4 | pergunta |
| Agentes | Agentes iniciados ou retomados a cada 10 minutos | 12 | pergunta |
| Agentes | Tokens processados por subagentes a cada 10 minutos | 10M | pergunta |
| Agentes | Subagentes que lançam seus próprios agentes | profundidade 1 | rejeita |
| Contexto | Aviso único para que Claude restrinja o turno | 300k tokens | adiciona uma nota |
| Contexto | Prompt que voltaria a ler este contexto | 500k tokens | pergunta: compactar e enviar, enviar igual ou cancelar |
| Contexto | Chamadas a ferramentas a cada 10 min com este contexto | 20 chamadas a 400k | pergunta |
| Contexto | Sessão pesada inativa o tempo suficiente para que expire seu cache | 150k tokens, 1 h inativa | pergunta antes de reescrever o cache |
| Loops | A mesma chamada falha uma e outra vez | 3 falhas idênticas | rejeita a retentativa idêntica |
| Loops | Agentes rejeitados em 10 minutos | 5 | pausa os lançamentos 10 min |
A regra da sessão inativa tem a ver com o cache de prompts, que explicamos em detalhes em Seu cache de 5 minutos não dura 5 minutos. Se ainda não usa subagentes, comece por Sub-agents em Claude Code.
Duas decisões de design importam no uso diário:
- Uma resposta vale por um tempo. Se você permite algo, o guard não volta a perguntar até que a condição desapareça. Uma janela do plano fica permitida até que se reinicie, e os contadores de agentes ficam permitidos durante 10 minutos. O autor o incorporou porque sua versão anterior perguntou 136 vezes em sessões de contexto alto e a resposta foi “sim” em 132.
- Sem uma pessoa, rejeita. Em
claude -p, no Agent SDK ou no mododontAsk, rejeita e explica o motivo. Claude lê a rejeição como o resultado da ferramenta, então pode esperar, agrupar o trabalho ou parar. As rejeições repetidas aumentam de tom, e a terceira pede a Claude que termine o turno.
O que faz o novo modo de encerramento ao 95 por cento?
Segundo o CHANGELOG da 1.1.0, quando qualquer janela do plano na máquina chega a 95 por cento, o próximo prompt de cada sessão leva uma nota para Claude: termina o passo em curso, não comeces nada grande e encerra o turno com o feito e o pendente.
O autor explica por que o adicionou. Os bloqueios que continuava vendo depois da 1.0 vinham de muitas sessões principais correndo em paralelo, e nenhuma regra o freava. Agora, quando chega o bloqueio, as encontra em um ponto limpo e não no meio de uma mudança. Uma sessão inativa também fica sabendo que outra sessão preencheu a janela. Cada sessão recebe o aviso uma única vez, e só volta a recebê-lo quando a janela cai do limite, por exemplo depois de seu reinício.
A versão 1.1.1, publicada no mesmo dia, corrige uma contagem dupla: desde Claude Code 2.1.299, retomar um subagente com SendMessage contava como dois inícios. Também faz com que /agent-guard status mostre qual versão está rodando.
Como se instala agent-usage-guard em Claude Code?
Dentro de Claude Code v2.1.287 ou posterior, execute:
/plugin marketplace add rbartoli/agent-usage-guard
/plugin install agent-usage-guard@agent-usage-guard
/reload-plugins
Depois execute /agent-guard para ver o que o guard vê.
Estos são os comandos que vai 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 executa sem iniciar um turno do modelo, assim Claude nunca vê uma anulação e não pode tomá-la como permissão.
Como se ajustam os limites?
Com variáveis de ambiente, ou dentro de env em ~/.claude/settings.json. Algumas das mais úteis:
AGENT_GUARD_AGENT_MAX: agentes correndo ao mesmo tempo na máquina (por padrão4).AGENT_GUARD_LIMIT_ASK_PERCENTeAGENT_GUARD_LIMIT_DENY_PERCENT: limites para perguntar e para rejeitar (80e95).AGENT_GUARD_CONTEXT_HARD: contexto a partir do qual um prompt pergunta antes de se enviar (500000).AGENT_GUARD=0: desliga o guard sem desinstalá-lo.
O README documenta 22 variáveis no total.
Funciona com uma chave de API?
Sim, com duas diferenças. As sessões com chave de API não reportam os percentuais da janela do plano, assim só se aplicam os orçamentos de tokens e de contagem de agentes. Além disso, o cache de prompts dura cinco minutos em vez de uma hora, assim o README recomenda AGENT_GUARD_DORMANT_SECONDS=300. O mesmo vale se usar uso adicional (extra usage).
O que não pode ver?
O README é explícito sobre seus pontos cegos, verificados contra Claude Code v2.1.295:
- Não conta sessões em outras máquinas, porque os registros compartilhados vivem no armazenamento de mods de cada máquina.
- Não vê os colegas de equipe (teammates) que rodam em seu próprio painel de terminal, porque rodam em outros processos.
- Os forks de
/subtask, e tudo que arranque sem o eventoagent.spawn, se contam mas nunca se retêm. - Não roda em uma sessão WSL do app de área de trabalho.
Os limites nativos de Claude Code seguem vigentes: uma sessão admite até 20 subagentes concorrentes e três níveis de aninhamento, mas não há limite ao total de agentes que uma sessão lança. Os valores por padrão do guard são mais estritos e abarcam todas as sessões.
É seguro instalar um mod de Claude Code?
Um mod roda com suas permissões e não está isolado em uma sandbox. A documentação de Anthropic o diz sem rodeios: um mod pode ler seus arquivos, suas variáveis de ambiente e sua sessão. Segundo as notas de privacidade do autor, o guard são cerca de 2.400 linhas de TypeScript sem dependências, não faz requisições de rede nem inicia processos, e guarda contadores e intervalos aproximados, nunca o texto dos prompts nem as entradas das ferramentas. Você pode revisar quais APIs usa com claude plugin validate . antes de instalá-lo.
No momento de publicar esta nota, o CHANGELOG lista duas correções de uma revisão de segurança de 24 de outubro de 2026 que ainda não fazem parte de uma versão publicada:
- Até que saia essa correção, qualquer outro plugin instalado podia executar
/agent-guard allowe levantar todos os limites por até oito horas. - Uma pergunta que terminava sem resposta podia deixar arrancar um agente; com a correção conta como “não”.
Antes de confiar no guard em sessões com outros mods instalados, comprove que sua versão inclua ambas as correções. Para revisar se qualquer mod é seguro, veja como testamos ModVet, o scanner que revisa um plugin antes de instalá-lo.
agent-usage-guard ou Claude HUD?
Resolven problemas distintos e funcionam bem juntos. Claude HUD te mostra o que Claude Code está fazendo e quanto te custa. agent-usage-guard lhe coloca um teto a esse custo e o aplica antes de que se gaste.
E você? Quantos subagentes deixa rodar em paralelo em Claude Code antes de começar a se preocupar com o limite?
- Várias vezes por semana
- De vez em quando
- Nunca
- Prefiro outra opção (conte-nos qual)
Comente abaixo ou, se este artigo chegou até você por email, responda diretamente ao email: sua resposta se publica aqui.
Relacionado: Claude HUD: O Plugin que te Diz Exatamente O Que Claude Code Está Fazendo (e Quanto te Está Custando)