Show HN: agent-usage-guard – a Claude Code mod to protect your usage window

GitHub README의 앞부분(소개, 설치, 동기, 보호 규칙, 질문·거부 동작)을 기준으로 옮겼어요. 그 뒤 설정 세부는 읽지 못했어요.

한 줄 소개

Claude Code가 5시간 사용량 창을 10분 만에 다 써 버리는 걸 막아 줘요.

agent-usage-guard는 Claude Code 안에서 실행되는 모드(mod)예요. 요금제의 실시간 사용량을 읽고, 서브에이전트 팬아웃(fan-out), 무거운 컨텍스트 반복, 재시도 루프를 지출이 일어나기 전에 붙잡아요. 에이전트가 시작되기 전, 프롬프트가 보내지기 전, 도구 호출이 실행되기 전에 판단해요.

왜 만들었나요

작성자는 어느 오후 최대 effort로 리서치 프롬프트를 줬더니 Claude Code가 서브에이전트 호출 394번(동시에 341개)을 띄우고 10분 만에 8,400만 컨텍스트 토큰을 API로 흘려보냈대요. 결과는 "Claude usage limit reached", 창이 리셋될 때까지 잠겼어요. 본인 로그 60일 치에서 잠김 12번, 에이전트 폭주가 있던 10분 구간 166개를 찾았다고 해요. 실패는 큰 컨텍스트 × 빠른 도구 루프 × 병렬 에이전트 × 맹목적 재시도로 곱해지고, 각 보호 장치가 이 인수를 하나씩 없앤다는 설명이에요.

특징

• 요금제 인식: Claude Code가 보고하는 5시간·주간 사용률을 읽어 창의 끝부분을 남겨 둬요.
• 한 번 승인하면 한동안 유효: 같은 질문이 매번 다시 뜨지 않아요.
• 로컬·최소 수집: 네트워크도 별도 프로세스도 없어요. 개수와 대략적 구간만 저장하고, 프롬프트·도구 입력·모델 출력은 저장하지 않아요.
• 실패 시 통과(fail open): 훅이 고장 나도 세션을 깨지 않아요. 예외는 제때 판단하지 못한 에이전트로, 거부해서 Claude가 다시 시작하게 해요.

무엇을 막나요

• 창이 일정 수준 차면 새 에이전트는 승인 필요, 더 차면 거부
• 5시간 창이 빠르게 오를 때 승인 필요
• 머신 전체에서 동시 실행 에이전트 수, 10분당 시작 수, 10분당 서브에이전트 토큰 수 제한
• 서브에이전트가 또 에이전트를 띄우는 것 금지
• 큰 컨텍스트를 다시 읽는 프롬프트는 "압축 후 전송 / 그냥 전송 / 취소"를 물어요
• 같은 도구 호출이 다른 호출 없이 연달아 실패하면 동일 재시도를 거부해요

묻는 방식과 거부 방식

키보드 앞에 사람이 있으면 Claude Code의 질문 대화창으로 물어요. 거절하면 10분 동안 에이전트를 띄우지 말라고 Claude에게 알리고, "haiku 에이전트를 대신 써" 같은 답도 전달돼요. claude -p, Agent SDK, dontAsk 모드처럼 답할 사람이 없으면 묻는 대신 거부하고 이유를 도구 결과로 알려 줘요. 같은 거부가 반복되면 문구를 바꿔 "다른 방법을 써라", "턴을 끝내라"로 점점 강해져요.

설치는 Claude Code v2.1.287 이상에서 /plugin marketplace add rbartoli/agent-usage-guard 뒤 /plugin install agent-usage-guard@agent-usage-guard예요. /agent-guard report로 무엇을 했는지 볼 수 있어요.