Claude Usage

Claude Code 사용량을 macOS 메뉴바에서 한눈에 보여주는 앱입니다.

기능

• 메뉴바 도넛 게이지 + 사용률(%) 표시
• 팝오버에서 5시간 / 주간 / 주간·Opus / 주간·Sonnet / 추가 사용량 확인
• 각 한도의 리셋 시각 표시
• 토큰 만료 시 자동 갱신, 일시적 오류 시 마지막 값 캐시 표시
• 잦은 호출에도 rate limit(HTTP 429)에 걸리지 않도록 설계

요구 사항

• macOS 13 (Ventura) 이상
• Claude Code에 로그인되어 있어야 합니다. 앱은 로컬 Keychain에 저장된 Claude Code 자격증명을 읽어 사용량을 조회합니다.

설치

소스에서 직접 빌드합니다.

# Swift 툴체인이 없다면 먼저: xcode-select --install
git clone https://github.com/oungo/claude-usage.git
cd claude-usage
./build.sh
open ClaudeUsage.app

빌드된 ClaudeUsage.app을 /Applications로 옮겨 두면 됩니다.

cp -R ClaudeUsage.app /Applications/

로그인 시 자동 시작 (선택)

시스템 설정 → 일반 → 로그인 항목에서 ClaudeUsage.app을 추가하면 부팅 시 자동 실행됩니다.

동작 방식

• 로컬 Keychain의 Claude Code-credentials에서 OAuth access token을 읽습니다. 최초 실행 시 macOS가 키체인 항목 접근 허용을 한 번 물어볼 수 있습니다(항상 허용을 누르면 이후 다시 묻지 않습니다).
• Anthropic의 /api/oauth/usage 엔드포인트를 호출해 사용량을 가져옵니다.
• access token이 만료됐거나 401이면 refresh token으로 자동 갱신합니다.
• 갱신된 토큰은 Claude Code와 동일한 포맷으로 로컬 Keychain에만 다시 저장됩니다.
• 모든 통신은 Anthropic 서버와만 이루어지며, 사용량 데이터나 토큰을 외부로 전송하지 않습니다.

/api/oauth/usage는 Anthropic의 비공식(undocumented) 엔드포인트로, 잦은 호출에 매우 공격적으로 rate limit(HTTP 429)이 걸립니다. 이 앱은 폴링 주기 5분, 연속 429 시 지수 백오프(5→15→30→60분), claude-code User-Agent, 디스크 캐시로 한도에 걸리지 않도록 동작합니다.

라이선스

MIT