Claude + Codex Usage
✨ Claude Usage란?
Claude.ai와 ChatGPT/Codex의 사용량을 메뉴바와 떠다니는 위젯으로 실시간 확인하는 macOS 앱입니다. 두 서비스의 서버가 제공하는 5시간·주간·모델별 한도를 함께 표시하며, Ultra처럼 5시간 한도가 없는 계정은 실제로 존재하는 한도만 보여줍니다.
- 🤖 Claude + Codex: 두 계정 상태를 독립적으로 조회하고 한 화면에 표시
- 👁️ 표시할 서비스: 하나만 쓴다면 다른 쪽을 끄세요. 끈 서비스는 메뉴바·드롭다운·위젯에서 빠지고 조회도 하지 않습니다
- 🎨 6가지 테마: 기존 당근 / 토스 / 하이브리드 유지 + 도넛 / 헤일로 바 / 오라 추가. 이전 테마 선택값도 유지합니다.
- 🪟 4가지 위젯 배치: 세로 / 가로 / 화살표 전환 / Claude·Codex 독립 위젯 중 선택, 끌어서 옮긴 위치를 기억
- Claude 주간 사용 구성: 7일 줄의 "구성"을 펼치면 Claude Code·채팅·Cowork 등의 비중이 게이지 색과 비율로 표시
- 🧭 새 모델 자동 대응: 서버가 내려주는 모델별 한도를 이름 고정 없이 표시하며 GPT-5.3-Codex-Spark는 기본 숨김·선택 표시
- 🧡 9종 선택형 펫: Mimo, Lumi, Kumo, Dot, Navi, Bori, Muru, Tori, Pico 중 하나를 고르고 반응 민감도와 애니메이션 조절
- 📈 로컬 사용량 그래프: 5분 간격 사용량을 이 Mac에만 14일 보관하고 기간·서비스별 추이를 별도 창에서 분석; 기본값은 꺼짐
- 🪶 적응형 네이티브 애니메이션: 편안할 때는 저주기로 움직이고 위젯을 숨기면 렌더링을 멈춰 상시 CPU 사용을 줄임
- 🌏 다국어: 한국어 / English — 즉시 토글
- 🔄 60초 자동 새로고침 + 수동 새로고침
- 🌑 다크 모드 자동 대응 (시스템 설정 따라감)
- 💻 Universal Binary (Intel + Apple Silicon)
Ultra 및 한도 자동 표시 (1.7.2)
- 기존 Max 20x와 새 Ultra 식별자는 Ultra로 표시합니다.
- 서버 응답에 없는 5시간 한도를
0%로 만들지 않습니다. 한도가 없어지거나 다시 생기면 다음 새로고침에 모든 테마·위젯·드롭다운에 반영됩니다.
- 메뉴바는 5시간 한도가 있으면 해당 사용률, 없으면 주간 사용률을 표시합니다. 둘 다 없으면
—이며, 실제 0%는 그대로 표시합니다.
- 주간·Fable 한도와 서버의 초기화 시각은 유지합니다. Anthropic 공식 안내에 따라 아직 임시 5시간 한도가 있는 Ultra 계정에서는 해당 한도를 계속 표시합니다.
주간 사용 구성
Claude 서버가 제공하는 seven_day_breakdown을 주간 사용량의 서비스별 비율로 표시합니다. 예를 들어 주간 한도 사용률이 35%, Code 비중이 90%라면, 해당 주간 사용량 중 90%가 Claude Code에서 발생했다는 뜻입니다. Code 한도를 90% 소진했다는 의미는 아닙니다.
- 메뉴바 드롭다운: Claude 7일 줄에 마우스를 올리면 펼쳐지고, 구성 버튼을 누르면 펼친 상태로 고정됩니다. 펼치면 7일 게이지가 Code·채팅·Cowork·기타 색으로 나뉘고 아래에 항목별 비율이 표시됩니다.
- 위젯: Claude의 7일 줄이나 주간 구성 제목에 마우스를 올리면 펼쳐집니다. 가로 위젯은 Codex 아래, 세로·전환·Claude 단독 위젯은 Claude 사용량 아래에 표시합니다. 위젯 밖으로 커서를 옮기면 접히며, 핀 버튼으로 펼침을 고정하거나 해제할 수 있습니다. 고정 여부는 재실행 후에도 유지됩니다.
- Codex 전용 위젯에는 Claude 구성이 나타나지 않습니다. 기존 3개와 새 3개 테마, 한국어·영어에서 모두 지원합니다. 기존 테마는 원래 크기와 형태를 유지하고, 새 게이지 3개는 같은 높이를 사용합니다.
이 내역은 계정의 이번 주 사용 구성으로, 이 Mac의 로컬 토큰 합계와는 별개입니다. 새로고침 때 서버가 제공하는 최신 집계를 표시하며 별도 한도·Mimo 최고 사용률에 포함하지 않습니다. 기존 버전이 잘못 저장했던 Breakdown 0%는 기록을 읽을 때 제외합니다. 실제 사용 내역은 로컬 추이 파일에 추가 저장하지 않습니다.
Codex는 현재 연동하는 응답에서 한도별 사용률과 계정 단위 일별 토큰을 제공하지만, Claude와 같은 서비스별 구성 비율은 제공하지 않습니다(2026-09-17 확인). Spark 등의 별도 한도 사용률은 전체 사용량에서 차지하는 비중이 아니므로 합산하거나 구성 비율로 바꾸지 않습니다. OpenAI 공식 App Server 문서
📸 스크린샷
1.7.2: Ultra와 실제 계정 한도에 맞춘 표시
실제 앱을 데모 데이터로 렌더링한 예시입니다. 88%·64%는 고정값이 아니며 실제 사용 시 서버에서 조회합니다. 6개 테마·4가지 배치에 동일하게 적용됩니다. 위젯 드래그 안정화, 우측 상단 − 숨기기 버튼, 숨긴 위젯의 렌더링 중지, 설정 아이콘 수정도 포함합니다. 전체 변경 내역
1.7.1: 새 앱 아이콘과 실제 초기화 알림
@jwoo5377의 PR #4로 세 줄 헤일로 게이지 아이콘을 적용했습니다. 앱은 다크 아이콘을 사용하고 이 README의 아이콘은 화면 모드에 따라 라이트·다크로 바뀝니다. macOS 앱 아이콘의 자동 모드 전환은 아닙니다.
사용자가 제공하고 공개를 요청한 실제 1.7.0 알림 수신 화면입니다. 새 로고 적용 전 캡처라 이전 주황 아이콘이 보입니다. 알림을 켜면 사용량 경고와 서버 조회로 확인한 초기화 등을 안내하며, 1.7.1에서도 같은 기능을 유지합니다.
1.7.0: 세 가지 게이지와 표시할 서비스
실제 앱을 데모 데이터로 렌더링한 화면입니다. 개인 계정, 대화 내용, 인증정보는 포함하지 않았습니다. 새로운 macOS 기능은 Windows 알파와 별도로 배포됩니다.
메뉴바 라벨
메뉴바에 Claude 아이콘과 퍼센트, Codex 아이콘과 퍼센트가 함께 표시됩니다. 각 서비스는 독립적으로 갱신되며, 설정에서 한 서비스를 끄면 켠 서비스만 표시됩니다.
드롭다운 (새 게이지 3종)
도넛은 사용률에 따라 고리가 파랑에서 주황, 빨강으로 이어지고, 헤일로 바는 빛이 번지는 그라데이션 막대, 오라는 사용률만큼 퍼지는 빛으로 보여 줍니다. 주황과 빨강은 경고(70%)와 위험(90%)에만 씁니다.
떠다니는 위젯 (새 게이지 3종)
위젯은 아무 곳이나 끌어서 옮길 수 있고, 옮긴 위치는 다음 실행에도 유지됩니다.
다국어 — 한국어 / English
설정 창
테마 / 위젯 배치 / 분리할 서비스 / Spark 표시 / 펫 / 로컬 기록 / 언어 / 표시할 서비스 — 모두 실시간 토글 가능. 변경 즉시 모든 화면에 반영됩니다. 설정 창 위쪽 로고도 고른 테마에 맞춰 바뀝니다.
로컬 사용량 그래프
메뉴바의 그래프 아이콘 또는 설정의 사용량 그래프 열기에서 1시간·24시간·7일·14일과 전체·Claude·Codex 범위를 전환할 수 있습니다.
9종 펫
아홉 펫은 같은 사용량·증가 속도 신호를 공유하지만 조명, 날씨, 픽셀, 궤도, 꼬리, 새싹, 날개, 배터리처럼 서로 다른 포즈와 소품으로 상태를 표현합니다. 자세한 동작은 펫 카탈로그를 참고하세요.
🚀 설치 (사용자)
- ClaudeUsage-1.7.2.dmg 다운로드 (모든 릴리스)
- dmg 열기 →
Applications 폴더로 드래그
- 처음 실행 전 ⬇️ 처음 실행 가이드를 꼭 한 번 봐주세요!
Codex 사용량 표시 조건: ChatGPT/Codex 앱 또는 호환되는 Codex 실행 파일이 설치되어 있고, 해당 Codex 세션에 로그인되어 있어야 합니다. GUI 앱을 계속 켜 둘 필요는 없습니다. ClaudeUsage가 조회할 때 로컬 codex app-server 프로세스를 직접 시작합니다.
Codex 앱 업데이트 호환: 최신 ChatGPT/Codex 앱의 Contents/Resources/codex-cli/CodexCLI.app/Contents/MacOS/codex와 기존 Contents/Resources/codex를 모두 지원합니다. /Applications, ~/Applications의 앱과 기존 CLI 설치 경로를 조회할 때마다 확인합니다. 앱 업데이트 후 Codex가 연결되지 않는다면 ClaudeUsage를 업데이트하세요. 로그인 정보나 사용 기록을 초기화할 필요는 없습니다. 초기화권 상세가 서버에서 null로 오는 경우에도 한도 조회를 유지합니다.
🔑 처음 실행할 때 읽어주세요
이 앱은 번들 무결성 검증용 ad-hoc 서명을 사용하며, Apple Developer ID 서명과 공증은 없습니다. macOS 보안 경고가 나타날 수 있습니다. 공식 릴리즈에서 받은 파일인지와 첨부된 SHA-256을 확인한 뒤 실행 여부를 결정하세요. 서명 검증만으로 앱의 안전성이 보장되지는 않습니다.
1) "확인되지 않은 개발자" 경고 우회
macOS 버전에 따라 다음 중 하나로:
macOS Sonoma (14) 이상 — 권장
ClaudeUsage.app 더블클릭 → "손상되어 휴지통으로 이동" 경고 뜨면 "취소"- 시스템 설정 → 개인정보 보호 및 보안 열기
- 아래로 스크롤 → "ClaudeUsage이(가) 차단되었습니다" 옆 "그래도 열기" 클릭
- 다시 한번 확인 다이얼로그 → "열기" 클릭
macOS Ventura (13) — 우클릭
- Applications 폴더에서
ClaudeUsage.app 우클릭(Control+클릭) → "열기"
- 경고 다이얼로그에서 "열기" 클릭 (1회만 — 이후부턴 더블클릭으로 OK)
터미널 한 줄 (가장 빠름, 모든 버전 동작)
xattr -dr com.apple.quarantine /Applications/ClaudeUsage.app
다운로드 파일에 자동으로 붙는 quarantine flag를 제거합니다. 이후 더블클릭만으로 실행됩니다.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
