richhickson/claudecodeusage

macOS menu bar app showing Claude Code usage limits (session/weekly/per-model/overage) with alerts and click-to-focus when a Claude Code session needs your attention

Claude Usage – Anthropic Claude Code를 위한 macOS 메뉴바 도우미

무엇인가요 – 메뉴바에 상주하며 Claude Code 할당량을 얼마나 사용했는지 실시간으로 보여주는 아주 작은 네이티브 Swift macOS 앱입니다. 또한 Claude Code 세션이 사용자의 입력을 기다리고 있을 때 알림을 보내주어, 세션이 실행 중인 터미널 탭으로 즉시 이동할 수 있게 해줍니다.

왜 중요한가요 – Claude Code(Anthropic의 Claude 모델을 위한 CLI)는 세션별, 주간 및 월간 사용량 제한을 적용합니다. 이러한 제한 사항을 모니터링하면 예상치 못한 초과 요금을 방지하고 세션이 조용히 멈추는 것을 방지할 수 있습니다.

핵심 기능

Feature	What you get
Usage tracking	현재 세션 사용량, 주간 제한(Fable/Opus와 같은 모델별 제한 포함), 월간 초과 지출액을 보여줍니다. 색상(초록색 < 70%, 노란색 ≥ 70%, 빨간색 ≥ 90%)을 통해 즉각적인 상태 확인이 가능합니다.
Auto-refresh	5분마다 Anthropic의 사용량 엔드포인트를 조회하며, 네트워크 또는 키체인 오류 발생 시 재시도하고, 잠자기 모드에서 깨어날 때 새로고침합니다.
Session alerts (opt-in)	Claude Code 세션이 사용자의 권한이나 입력이 필요할 때 종 모양 아이콘과 숫자가 나타납니다. macOS 알림은 켜고 끌 수 있으며, 알림이나 목록 항목을 클릭하면 해당 Terminal/iTerm2 탭으로 즉시 이동합니다.
Live session list	팝오버 메뉴에서 각 추적 세션의 상태를 확인할 수 있습니다: 필요함 🔔, 작업 중 ⚙️, 또는 완료됨 ✅.
Claude Code settings editor	앱에서 전역 `CLAUDE.md` 파일을 편집하고 로컬 트랜스크립트 보관 기간을 제어하는 `cleanupPeriodDays`를 조정할 수 있습니다.
Convenience	로그인 시 자동 실행 토글, 내장 업데이트 확인 기능, 그리고 가벼운 사용량(네이티브 Swift, 추가 런타임 없음)을 제공합니다.

내부 작동 원리

Credentials – 앱은 macOS Keychain에서 Claude Code OAuth 토큰을 읽어옵니다(비밀번호는 기기에 절대 남지 않습니다).
Usage data – 문서화되지 않은 Anthropic 엔드포인트 api.anthropic.com/api/oauth/usage를 호출하여 할당량 정보를 가져옵니다.
Session monitoring – 알림을 활성화하면, 앱은 ~/.claude/settings.json에 작은 POSIX-sh 훅(hook)을 작성합니다. Claude Code는 각 세션마다 이 훅을 실행하여 ~/.claude/claudeusage/에 JSON 상태 파일을 작성합니다. 메뉴바 앱은 해당 디렉토리를 감시하고 그에 따라 UI/알림을 업데이트합니다.
Click-to-focus – macOS 접근성 권한을 통해 앱이 Terminal/iTerm2에 세션 ID와 일치하는 탭을 선택하도록 명령할 수 있어, 즉시 응답할 수 있습니다.

설치 및 시작하기

Download – Releases 페이지에서 최신 ClaudeUsage.zip을 다운로드하고, 압축을 푼 뒤 ClaudeUsage.app을 Applications 폴더로 드래그합니다.
First launch – 처음 실행할 때 오른쪽 클릭 → Open을 선택합니다(macOS가 서명되지 않은 앱에 대해 경고를 표시할 수 있습니다). 앱은 자동으로 Claude Code 인증 정보를 찾아냅니다.
Optional – build from source – 저장소를 클론하고, Xcode에서 ClaudeUsage.xcodeproj를 열어 ⌘B로 빌드하고 ⌘R로 실행합니다.
Enable alerts – 메뉴바 팝오버의 톱니바퀴 아이콘을 클릭하고 Alert when a session needs attention을 토글합니다. 앱이 ~/.claude/settings.json에 훅을 대신 설치/제거해 줍니다.

요구 사항

macOS 13 (Ventura) 이상
Claude Code CLI 설치 (npm i -g @anthropic-ai/claude-code) 및 로그인 상태 (claude)

개인정보 보호 및 라이선스

텔레메트리(telemetry) 없음; 유일한 네트워크 호출은 Anthropic의 공식 사용량 API입니다.
MIT 라이선스 소스 – 자유롭게 감사하거나 수정할 수 있습니다.
비공식 도구 – Anthropic과 관련이 없으며, 변경될 수 있는 문서화되지 않은 API에 의존합니다.

Made by @richhickson