claude-quota: Claude Code를 위한 macOS 메뉴 바 게이지

개요

claude-quota는 Claude Code 할당량 사용량을 즉시 확인할 수 있도록 설계된 macOS 메뉴 바 유틸리티입니다. SwiftBar 플러그인으로 제작되어, 사용자가 Claude Code CLI 내에서 /usage 명령어를 수동으로 확인할 필요 없이 macOS 메뉴 바에서 5시간 단위 사용량과 주간 제한을 직접 모니터링할 수 있게 해줍니다.

주요 기능 및 시각적 지표

이 도구는 색상으로 구분된 게이지 시스템을 사용하여 할당량 상태를 한눈에 파악할 수 있도록 합니다:

  • 5시간 단위 사용량: 게이지는 초록색, 주황색(70% 이상 시), 또는 빨간색(90% 이상 시)으로 표시됩니다.
  • 리셋 카운트다운: 5시간 단위 사용량이 완전히 소진되면, 게이지는 퍼센트 대신 다음 리셋까지의 카운트다운 타이머를 표시합니다 (예: 4:28).
  • 주간 제한 알림: 주간 제한에 도달하면 게이지가 검은색으로 변하며 주간 리셋까지의 카운트다운을 표시합니다 (예: 2D). 이 주간 제한은 5시간 단위 상태보다 우선순위를 가집니다.
  • 상세 드롭다운: 게이지를 클릭하면 5시간 및 주간 단위, 모델별 단위(해당하는 경우), 추가 사용 크레딧, 정확한 리셋 시간 등 모든 계정에 대한 상세 내역이 표시됩니다.
  • 새로고침 빈도: 플러그인은 기본적으로 5분마다 새로고침되며, 드롭다운 메뉴에서 수동 "Refresh now" 옵션을 사용할 수 있습니다.

기술적 구현

데이터 검색

claude-quota는 macOS Keychain에서 Claude Code OAuth 토큰을 읽기 전용 방식으로 읽어와 사용량 데이터를 가져옵니다. 그런 다음 Claude Code /usage 화면에서 사용하는 것과 동일한 내부 비공개 엔드포인트를 쿼리합니다. 토큰을 새로고침하거나 다시 쓰지 않기 때문에 사용자의 세션을 로그아웃시키지 않습니다.

계정 관리

기본적으로 플러그인은 관련 Keychain 항목이 있는 ~/.claude 또는 ~/.claude-* 설정 디렉토리를 스캔하여 계정을 자동으로 검색합니다.

  • 레이블링: 자동으로 검색된 계정은 디렉토리 접미사로 레이블이 지정됩니다 (예: ~/.claude-work는 W가 됩니다). 단일 계정인 경우 레이블이 표시되지 않습니다.
  • カスタマイズ (Customization): 사용자는 ~/.config/claude-quota/accounts 파일에 한 줄당 하나의 path [label] 형식을 작성하여 계정을 고정하거나 이름을 변경할 수 있습니다.
  • 가시성: 특정 계정은 드롭다운 메뉴를 통해 메뉴 바 게이지에서 숨기거나 ~/.config/claude-quota/hidden 파일을 편집하여 숨길 수 있습니다.

설치 및 설정

빠른 설치

사용자는 쉘 스크립트를 통해 도구를 설치할 수 있습니다: curl -fsSL https://raw.githubusercontent.com/grzegorz-raczek-unit8/claude-quota/main/install.sh | bash

수동 설치

또는 사용자는 git checkout을 통해 설치할 수 있습니다:

  1. git clone https://github.com/grzegorz-raczek-unit8/claude-quota.git
  2. cd claude-quota
  3. ./install.sh

요구 사항: 이 도구는 macOS와 Homebrew가 필요합니다. 첫 번째 새로고침 시, macOS Keychain 권한 대화 상자가 나타나면 "Always Allow"를 선택해야 합니다.

커뮤니티 논의 및 대안

Hacker News의 커뮤니티 피드백은 AI 할당량 사용량을 추악적하는 다양한 대안 도구들을 강조하며, 유사한 유틸리티리티의 포화된 생태계를 시사했습니다. 사용자들은 다음과 같은 여러 대안을 언급했습니다:

  • CodexBar 및 usage4claude: Codex를 포함한 여러 제공업체를 지원하는 도구입니다.
  • ClaudeCodeStatusLine: Claude Code CLI 상태 라인에 사용량 데이터를 직접 통합하는 플러그인입니다.
  • codeburn 및 RateLimited: 다른 메뉴 바 또는 터미널 기반 추적기입니다.
  • claudebar: Hyprland/Waybar를 위한 Linux 기반 대안입니다.

일부 사용자는 (curl을 bash로 파이핑하는) 설치 방식에 대한 우려를 표명한 반면, 다른 사용자들은 Claude Code CLI 상태 바에 기본 할당량 표시기가 없는 것이 이러한 서드파티 도구 제작의 주요 동인임을 언급했습니다.

Sources