Claude Code 사용량, 메뉴바에서 한눈에

왜 만들었나

Claude Code를 쓰다 보면 피할 수 없는 게 사용량 제한이다. 5시간 단위, 7일 단위로 사용량이 관리되는데, 문제는 지금 내가 얼마나 썼는지 확인할 방법이 마땅치 않다는 것.

비슷한 기능의 도구를 찾아서 써봤는데, 내 입맛에 딱 맞지 않았다. 무엇보다 권한 요청이 반복적으로 뜨는 게 불편했다. 쓸 때마다 허용 팝업이 뜨니 집중이 깨진다.

그래서 직접 만들기로 했다. 목표는 단순했다 — 메뉴바에서 한눈에, 설정 없이 바로 동작하는 앱.

뭘 만들었나

Claude Usage Monitor는 macOS / Windows 메뉴바(트레이)에서 Claude Code 사용량을 실시간으로 보여주는 데스크톱 앱이다.

메뉴바에 Pill 형태의 뱃지로 사용률(%), 남은 시간, 비용 등을 표시한다.

핵심 특징을 정리하면:

주요 기능 — 팝업 대시보드

메뉴바 pill을 클릭하면 상세 대시보드가 열린다.

대시보드에 표시되는 데이터는 두 가지 출처로 나뉜다.

실시간 API 데이터 — 5H/7D 사용률(%), 리셋까지 남은 시간
Anthropic API 응답 헤더에서 직접 가져오는 값으로, 실제 서버 기준의 정확한 수치다.

로컬 데이터 — 토큰 수, 비용, 요청 수, 모델별 breakdown, 주간 차트
로컬 PC에 저장된 Claude Code 로그 파일(~/.claude/projects/)을 파싱한 값이다. 비용은 공개된 API 가격 기준의 추정치로, 실제 청구 금액과 다를 수 있다.

5-Hour / 7-Day 사용률

• 실시간 API 데이터 기반 사용률(%)을 프로그레스 바로 표시
• 리셋까지 남은 시간을 카운트다운으로 보여줌

모델별 상세 정보 (로컬 데이터)

• Today — 오늘 누적 토큰, 비용, 요청 수
• 5-Hour Block — 현재 5시간 윈도우 내 모델별(Opus/Sonnet/Haiku) breakdown
• 7-Day Total — 주간 합산

This Week 차트

• 일별 비용 바 차트로 한 주간 사용 추이를 한눈에 확인

알림

• 사용률 임계값(50%, 75%, 90% 등)에 도달하면 macOS 알림 발송
• 5H / 7D 각각 별도 임계값 설정 가능

메뉴바 커스터마이징

• 표시할 항목 선택, 드래그로 순서 변경

• 구분자 스타일 선택 ( ·

  / 공백)

• 동적 색상 ON/OFF, 그룹별 고정 색상 지정

설정

팝업 우측 상단 톱니바퀴 아이콘을 누르면 설정 화면으로 진입한다.

메뉴바 항목

• General / 5H Session / 7D Weekly 그룹별로 표시할 항목을 체크박스로 선택
• 드래그로 순서 변경 가능
• Plan, Usage %, Reset In, Block Cost 등 원하는 조합으로 구성

테마 / 색상

• 다크 / 라이트 테마 전환
• Launch at login — 시스템 부팅 시 자동 실행
• Pill 배경 색상 — 그룹별로 고정 색상 지정 가능
• Dynamic Pill Colors — 사용률에 따라 자동 색상 변경 (0~50% 초록, ~75% 노랑, ~90% 주황, 90%+ 빨강)
• Preview — 현재 설정이 메뉴바에 어떻게 보이는지 미리보기

업데이트

• 설정 하단 About & Update 섹션에서 현재 버전 확인 가능
• Check Again 버튼으로 새 버전이 있는지 확인하고, 있으면 직접 다운로드하여 업데이트할 수 있다

어떻게 동작하나

인증

macOS Keychain(또는 Windows Credential Manager)에서 Claude Code의 OAuth 인증 정보를 자동으로 읽는다. 앱 자체에 로그인 기능은 없다. Claude Code CLI에 로그인되어 있으면 그대로 동작한다.

처음 실행 시 macOS에서 Keychain 접근 허용을 물어볼 수 있다 — “항상 허용”을 선택하면 이후 다시 묻지 않는다.

사용률 조회

Anthropic API에 최소한의 Haiku 요청(max_tokens: 1)을 보내고, 응답 헤더에서 사용률 정보를 읽는다.

anthropic-ratelimit-unified-5h-utilization: 0.04
anthropic-ratelimit-unified-7d-utilization: 0.02
anthropic-ratelimit-unified-5h-reset: <unix-timestamp>
anthropic-ratelimit-unified-7d-reset: <unix-timestamp>

요청 한 번에 약 9토큰, 비용은 $0.001 미만이다.

토큰 / 비용 집계

~/.claude/projects/ 하위의 JSONL 파일을 로컬에서 파싱하여 모델별 토큰, 비용, 요청 수를 집계한다. Worker Thread와 mtime 캐시를 사용해서 변경된 파일만 다시 읽기 때문에 성능 부담이 적다.

프라이버시

• api.anthropic.com 외에 어떤 외부 서비스와도 통신하지 않는다
• 텔레메트리, 분석, 제3자 서비스 없음
• 모든 데이터는 로컬에서 처리

설치 및 사용법

전제 조건

• Claude Code CLI가 설치되어 있고 로그인된 상태 (Pro / Max / Team 구독)
• 아직 로그인하지 않았다면 터미널에서 claude를 실행하여 로그인

다운로드

GitHub Releases에서 최신 버전을 다운로드:

macOS: 압축 해제 → Applications로 이동 → 우클릭 → 열기 (최초 1회)

Gatekeeper가 차단하는 경우:

xattr -cr /Applications/Claude\ Usage\ Monitor.app

위 명령 실행 후 다시 열면 된다.

소스에서 빌드

git clone https://github.com/baekhj/claude-usage-monitor.git
cd claude-usage-monitor
npm install
npm start

릴리즈 히스토리

GitHub 저장소는 여기에서 확인할 수 있다.