콘텐츠로 이동
Belloga

0011. Claude 사용량을 OAuth 사용량 API로도 가져온다

맥락

섹션 제목: “맥락”

Belloga는 Claude 사용량을 Claude Code의 statusLine 훅으로 받기만 했다. statusLine은 Claude 세션이 돌 때, 그것도 일부 틱에만 rate_limits를 실어 보내므로 앱이 원할 때 새로 가져올 방법이 없었다. 또 Fable 주간 사용량은 statusLine에 들어오지 않는다.

상태 바에 Orca와 같은 갱신 단추와 Fable 주간 사용량을 두려면 사용량을 앱이 직접 가져올 경로가 필요하다.

결정

섹션 제목: “결정”

Claude Code가 저장해 둔 OAuth 토큰으로 https://api.anthropic.com/api/oauth/usage를 불러 5시간, 주간, Fable 주간 사용량을 얻는다. 요청 헤더와 주기는 Orca와 같다.

  • 토큰은 macOS에서는 키체인의 Claude Code-credentials 항목에서, 없거나 다른 OS면 ~/.claude/.credentials.json에서 읽는다.
  • 렌더러의 상태 바가 마운트될 때 한 번, 그 뒤 15분마다, 그리고 갱신 단추를 누를 때 가져온다. 요청은 10초가 지나면 끊는다.
  • statusLine 값과 API 값은 같은 사용량 상태에 합치고, 창마다 나중에 들어온 값이 이긴다.
  • 토큰이 없거나 요청이 실패하면 로그 한 줄만 남기고 이전 값을 둔다.
  • 토큰은 메인 프로세스 밖으로 나가지 않는다. 렌더러, 로그, 저장 파일 어디에도 남기지 않는다.

근거 / 검토한 대안

섹션 제목: “근거 / 검토한 대안”
  • statusLine만 쓴다. 사용자의 인증 정보를 읽지 않아도 된다. 그러나 갱신 단추가 할 일이 없고, Fable 주간 값을 얻을 수 없다.
  • Claude CLI의 /usage 화면을 PTY로 읽는다(Orca의 대체 경로). 토큰을 직접 읽지 않는다. 그러나 CLI를 한 번 띄우는 비용이 크고, 화면 글을 해석하므로 CLI가 바뀌면 깨지기 쉽다.
  • 채택안: Orca의 기본 경로와 같은 OAuth API를 쓴다. Orca의 PTY 대체 경로와 토큰 갱신(repairClaudeCredentialsThenRetryOAuth)은 가져오지 않는다. API가 실패하면 statusLine 값만 남는다.

결과

섹션 제목: “결과”
  • 앱이 사용자의 Claude 인증 정보를 읽는다. macOS에서는 처음 읽을 때 키체인 접근을 허락할지 묻는 창이 뜰 수 있다. Orca도 같은 방식이다.
  • API 키로 Claude Code를 쓰는 사용자는 토큰이 없어서 지금처럼 statusLine 값만 본다.
  • 토큰이 만료되면 Claude Code가 다시 갱신할 때까지 API 요청이 실패하고, 그동안은 statusLine 값만 들어온다.
  • 공개되지 않은 API라 응답 모양이 바뀔 수 있다. 해석은 mapOAuthUsage 한 곳에 모아 두었다.