Claude Code의 사용량 제한 도달 전 경고 및 작업 이관을 위한 agent-baton 개발

Claude Code가 아무런 예고 없이 사용량 제한(rate limits)에 걸리는 것에 지쳐서, 작업 도중에 차단되지 않도록 이 문제를 해결할 도구를 만들기로 했습니다.

리팩터링(refactor)을 시작한 지 40분이 지났다고 상상해 보세요. Claude가 도구(tools)를 실행하며 진행 중인데, 갑자기 모든 것이 멈춰버립니다. 아무런 경고 없이—사용량이 95%에 도달했다는 알림도 없이—세션이 사용량 제한에 도달하여 완전히 중단된 것입니다. UI에는 사용량 바(usage bars)가 보이지만, 모델 자체는 이를 인지하지 못합니다.

저는 Anthropic이 사용량 API(usage API)를 제공하며, Claude Code가 이를 작동시키기 위한 훅(hooks)을 이미 보유하고 있다는 사실을 발견했습니다. 이를 통해 사용량 API를 읽고 Claude가 자신의 제한 사항을 인지할 수 있도록 훅을 설치하는 agent-baton을 만들게 되었습니다.

한 번의 명령(baton init)으로 시작할 수 있는 세 가지 훅은 다음과 같습니다:

1. SessionStart: 사용량 데이터를 가져와 주입함으로써, Claude가 첫 메시지부터 얼마나 사용되었는지 알 수 있게 합니다.
2. UserPromptSubmit: API에 과부하를 주지 않도록 TTL(Time-To-Live)을 고려한 체크를 수행합니다. 스마트 캐싱(smart caching)을 사용하여 사용량이 적을 때는 15분마다, 제한에 가까워지면 1분마다 확인합니다.
3. PreToolUse: 이것이 가장 핵심적인 기능입니다. 작업 중간에 사용량을 확인하여, "93% 상태에서 시작했다가 실행 도중에 용량이 소진되는" 상황을 방지하며, 1~2회의 도구 호출(tool calls) 내에 문제를 포착합니다.

경고 임계값(warning threshold)에 도달하면, Claude Code의 내장된 AskUserQuestion 도구를 사용하여 다음과 같은 대화형 질문을 표시합니다:

"Claude 5시간 사용량이 91%입니다 — 경고 구역에 진입했습니다."

선택 옵션은 다음과 같습니다:

• 이 작업 계속하기 (Continue this task)
• 인수인계 문서 작성하기 (Write a handoff document)
• 경량 모드로 전환하기 (Switch to lightweight mode)

또한 구조화된 마크다운(markdown) 인수인계 문서를 작성하여 Cursor, Codex 또는 Gemini로 작업을 전달함으로써 완전한 에이전트 인수인계(agent handoffs)를 처리합니다.

다음 명령어로 설치할 수 있습니다:

npm install -g u/codeprakhar25/agent-baton && baton init

더 자세한 내용은 GitHub repository를 방문하세요.