Repolode
제출하기
rbartoli

rbartoli/agent-usage-guard

플랜의 사용량 한도를 소진하기 전에 서브에이전트 분산 실행, 컨텍스트가 큰 프롬프트, 재시도 루프를 제어하는 Claude Code 모드입니다.

GitHub에서 보기
스타
94
포크
5
열린 이슈
0
마지막 커밋
그저께

어떤 프로젝트인가요?

agent-usage-guard는 Claude Code용 모드로, 각 에이전트 시작, 프롬프트, 도구 호출이 실행되기 전에 확인합니다. 플랜에 표시된 5시간 및 주간 사용량 비율을 읽고, 컴퓨터의 모든 Claude Code 세션에서 실행 중이거나 최근에 실행된 에이전트 수를 집계합니다. 한도에 도달하면 Claude Code 자체의 질문 대화상자에서 확인을 요청합니다. claude -p나 Agent SDK처럼 응답할 사람이 없는 경우에는 실행을 거부하고 이유를 설명합니다.

기본 규칙은 동시 에이전트 수를 4개로 제한하고, 10분당 시작 횟수를 12회로 제한하며, 각 사용량 구간에서 서브에이전트 토큰을 1,000만 개로 제한합니다. 또한 500k 토큰을 다시 읽게 될 프롬프트나 컨텍스트가 큰 상태에서 이어지는 도구 호출 같은 대규모 컨텍스트 사용도 감지합니다. 승인은 조건이 해소되거나 시간 초과될 때까지 유지되므로 호출할 때마다 같은 질문을 반복하지 않습니다. 이 가드는 오류가 발생해도 실행을 허용합니다. 훅 중 하나에서 오류가 나면 해당 이벤트는 계속 진행됩니다.

네트워크에 접속하거나 백그라운드 프로세스를 실행하지 않고 로컬에서 작동합니다. 프롬프트 텍스트, 도구 입력 또는 모델 출력은 저장하지 않고, 횟수와 대략적인 구간만 저장합니다. /agent-guard report 명령으로 개입 내역을 요약해 볼 수 있습니다.

핵심 기능

  • 01플랜의 5시간 또는 주간 사용량이 설정된 임계값을 넘으면 새 에이전트를 시작하기 전에 확인을 요청합니다.
  • 02컴퓨터의 모든 세션에서 동시 에이전트 수, 에이전트 시작 횟수, 서브에이전트 토큰을 제한합니다.
  • 03대규모 컨텍스트를 다시 읽게 될 프롬프트를 실행하기 전에 확인을 요청하고, 컨텍스트가 큰 상태에서 이어지는 도구 호출을 제한합니다.
  • 04반복 실패 후 동일한 도구 재시도를 거부합니다.
  • 05네트워크 접속 없이 로컬에서 실행되며 프롬프트나 도구 콘텐츠를 저장하지 않습니다.
  • 06/agent-guard report로 개입 내역을 요약합니다.

활용 사례

  • 5시간 사용량 한도를 소진하지 않고 Claude Code에서 병렬 조사나 멀티 에이전트 워크플로를 실행합니다.
  • 차단 상태에 빠지는 대신 에이전트의 과도한 분산 실행을 거부해야 하는 claude -p 또는 Agent SDK 작업을 스크립팅합니다.
  • 장시간 실행되는 세션에서 반복 재시도로 컨텍스트가 소모되는 것을 방지합니다.

빠른 시작

  1. 1

    Claude Code에 마켓플레이스를 추가합니다

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

    플러그인을 설치합니다

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

    플러그인을 다시 불러옵니다

    /reload-plugins
  4. 4

    status 명령을 실행해 guard가 무엇을 감지하는지 확인합니다

    /agent-guard

사용 전 알아둘 점

  • Claude Code v2.1.287 이상이 필요합니다.
  • /subtask 포크나 각자 터미널 창에서 실행 중인 팀원 등 일부 경로는 지원되지 않습니다.
  • API 키 세션에서는 Plan 창 읽기를 사용할 수 없습니다.
  • Desktop 앱의 WSL 세션에서는 실행되지 않습니다.

포함된 컬렉션

Claude Code 도구·스킬·플러그인오픈소스 AI 에이전트 프레임워크와 앱

토픽

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

자주 묻는 질문

agent-usage-guard은(는) 무엇인가요?
플랜의 사용량 한도를 소진하기 전에 서브에이전트 분산 실행, 컨텍스트가 큰 프롬프트, 재시도 루프를 제어하는 Claude Code 모드입니다. agent-usage-guard는 Claude Code용 모드로, 각 에이전트 시작, 프롬프트, 도구 호출이 실행되기 전에 확인합니다. 플랜에 표시된 5시간 및 주간 사용량 비율을 읽고, 컴퓨터의 모든 Claude Code 세션에서 실행 중이거나 최근에 실행된 에이전트 수를 집계합니다. 한도에 도달하면 Claude Code 자체의 질문 대화상자에서 확인을 요청합니다. claude -p나 Agent SDK처럼 응답할 사람이 없는 경우에는 실행을 거부하고 이유를 설명합니다.
agent-usage-guard은(는) 무료로 사용할 수 있나요? 라이선스는 무엇인가요?
agent-usage-guard은(는) MIT 라이선스의 오픈소스입니다. 상업용 제품에 사용하기 전에 라이선스 조건을 확인하세요.
agent-usage-guard은(는) 아직 유지보수되고 있나요?
활발히 유지보수 중. agent-usage-guard의 마지막 커밋은 2026년 11월 6일입니다.
agent-usage-guard은(는) 어디에 사용할 수 있나요?
5시간 사용량 한도를 소진하지 않고 Claude Code에서 병렬 조사나 멀티 에이전트 워크플로를 실행합니다. 차단 상태에 빠지는 대신 에이전트의 과도한 분산 실행을 거부해야 하는 claude -p 또는 Agent SDK 작업을 스크립팅합니다. 장시간 실행되는 세션에서 반복 재시도로 컨텍스트가 소모되는 것을 방지합니다.
agent-usage-guard는 어떻게 설치하나요?
Claude Code에 마켓플레이스를 추가합니다: /plugin marketplace add rbartoli/agent-usage-guard 플러그인을 설치합니다: /plugin install agent-usage-guard@agent-usage-guard 플러그인을 다시 불러옵니다: /reload-plugins status 명령을 실행해 guard가 무엇을 감지하는지 확인합니다: /agent-guard
agent-usage-guard은(는) 어디서 받을 수 있나요?
소스 코드와 설치 방법은 GitHub에 있습니다: https://github.com/rbartoli/agent-usage-guard

요약은 프로젝트 README를 바탕으로 AI가 작성했습니다. GitHub 통계는 매일 갱신됩니다.

관련 프로젝트