Claude Code 사용량 제한 경고 및 작업 전환 도구 개발
Made claude code warn you, time before it hits usage to transfer the pending work, all dynamically
핵심 요약
Claude Code 사용 중 갑작스러운 속도 제한을 방지하고 작업 전환을 돕는 도구 'agent-baton'을 개발함.
- 사용량 모니터링 — Claude Code의 API 사용량을 실시간으로 추적하여 제한 도달 전 경고함.
- 작업 전환 지원 — 작업 중단 시 Cursor나 다른 도구로 작업을 넘길 수 있는 핸드오프 기능을 제공함.
- 스마트 알림 — 사용량에 따라 체크 주기를 조절하여 API 호출 효율을 최적화함.
- 간편한 설치 — npm 명령어를 통해 즉시 초기화하고 사용할 수 있음.
Claude Code를 쓰다가 예고 없이 속도 제한(rate limit)에 걸리는 게 지겨워져서, 작업 도중에 차단당하지 않도록 해결책을 직접 만들기로 했습니다.
리팩토링을 40분 정도 진행하고 있다고 상상해 보세요. Claude가 툴을 실행하며 작업을 진척시키다가 갑자기 모든 게 멈춰버립니다. 경고도 없이 세션이 속도 제한에 도달한 거죠. 95%에 도달했다는 알림도 없이 그냥 완전히 멈춰버립니다. UI에는 사용량 막대가 보이지만, 모델 자체는 그 상태를 전혀 인지하지 못합니다.
Anthropic이 사용량 API를 제공하고 있고, Claude Code에는 이미 이를 활용할 수 있는 훅(hook)이 있다는 걸 발견했습니다. 그래서 저는 사용량 API를 읽고 Claude가 제한을 인지하도록 훅을 설치하는 'agent-baton'을 만들게 되었습니다.
다음은 한 번의 명령(baton init)으로 시작할 수 있는 세 가지 훅입니다:
- SessionStart: 사용량 데이터를 가져와 주입함으로써 Claude가 첫 메시지부터 사용량을 알 수 있게 합니다.
- UserPromptSubmit: API에 과부하를 주지 않도록 TTL(Time-To-Live) 기반의 체크를 수행합니다. 스마트 캐싱을 사용하여 사용량이 낮을 때는 15분마다, 제한에 가까워지면 1분마다 체크합니다.
- PreToolUse: 가장 중요한 부분입니다. 작업 중간에 사용량을 체크하여 "93%에서 시작했는데 실행 도중에 용량이 바닥나는" 상황을 방지하며, 1~2번의 툴 호출 내에서 문제를 잡아냅니다.
경고 임계값에 도달하면 Claude Code의 내장 툴인 AskUserQuestion을 사용하여 대화형 질문을 던집니다:
"Claude 5시간 사용량이 91%입니다 — 경고 구간에 진입했습니다."
선택지는 다음과 같습니다:
- 이 작업 계속하기
- 핸드오프 문서 작성하기
- 라이트 모드로 전환하기
또한 구조화된 마크다운 핸드오프 문서를 작성하여 Cursor, Codex, Gemini로 작업을 넘기는 전체 에이전트 핸드오프 기능도 처리합니다.
다음 명령어로 설치할 수 있습니다:
npm install -g @codeprakhar25/agent-baton && baton init
더 자세한 내용은 GitHub 저장소를 방문해 주세요.
