Codex CLI의 5시간 및 주간 사용량을 macOS 메뉴 바에서 바로 확인하는 작은 네이티브 앱입니다. 실행하면 Dock 아이콘이나 일반 창 없이 메뉴 바에만 아이콘이 나타납니다.
- 계정별 5시간·주간 사용률, 남은 비율, 초기화 시각 표시
- 바깥쪽 5시간 링과 안쪽 주간 링에 각각의 남은 퍼센트 표시
- 리셋 크레딧 개수와 서버가 제공하는 가장 빠른 소멸 시각 표시
- 현재 머신의 기본 Codex 연결과 앱에 추가한 여러 ChatGPT 계정·워크스페이스 동시 확인
- 메뉴 바 숫자는 5시간 잔량, 배터리 테두리 안의 음양 반전 채움은 주간 잔량으로 표시
- 기어 옵션에서 음양 반전 터미널형 또는 주간 링 + 5시간 숫자형 선택
- 추가 연결은 15분마다 자동 갱신하고, 메뉴를 열 때 모든 연결을 순차 갱신 및 수동 새로고침
- 기어 옵션에서 현재 머신의 기본 연결 갱신 주기를 30초·1분·5분·10분·30분·1시간 중 선택
- 기본 연결 조회가 실패하거나 다른 조회와 겹치면 즉시 재시도하지 않고, 간격을 자동 조정하지 않은 채 선택한 다음 주기에 다시 한 번 시도
- 연결별 Codex app-server 프로세스를 재사용하고, 짧은 시간 안의 중복 새로고침 요청은 한 번으로 합침
- 일시적인 조회 실패에는 마지막 정상 사용량을 유지하고 경고 아이콘을 표시하며, 서버의 사용량 변경 알림도 즉시 반영
- 선택 시 각 연결에 5시간마다 한 번씩 가벼운 무도구 산술 요청을 보내되 연결별 시작을 최소 30분 간격으로 순차 실행
- Node.js나 별도 Codex CLI 설치 없이 동작하는 네이티브 Codex 런타임 내장
- 기존
~/.codex로그인을 자동 재사용해 중복 로그인 방지 - 추가한 계정/워크스페이스마다 독립된
CODEX_HOME과 브라우저 기기 코드 로그인 사용 - 한 ChatGPT 계정의 여러 워크스페이스를 별도 연결로 등록하고 각각의 사용량 확인
- 기기 코드 인증 완료 시 별도 확인 단계 없이 연결을 자동 추가하고 동일 계정·워크스페이스 조합은 차단
- 인증 코드 패널에서 워크스페이스 표시 이름을 지정하고 각 연결의 연필 버튼으로 언제든 수정
- 계정 이름 변경, 재로그인 및 로컬 로그인 정보 삭제 지원
- 연결 작업 알림은 닫기 버튼을 제공하고 성공은 5초, 오류는 10초 후 자동으로 사라짐
- macOS의 표준 로그인 항목(
SMAppService) 선택 지원 - Dock에 나타나지 않는 표준 메뉴 바 앱(
LSUIElement)
앱은 함께 배포되는 Codex 네이티브 실행 파일과 공식 로컬 app-server 프로토콜인 account/rateLimits/read 및 account/rateLimits/updated를 사용합니다. 각 계정은 하나의 초기화된 app-server 연결을 계속 재사용하고, 연결이 실제로 종료되거나 시간 초과되면 자동 연속 재시도하지 않고 다음 예약 주기에 새 연결을 만듭니다. 앱은 중복 계정 판별과 외부 계정 전환 감지를 위해 auth.json의 계정/워크스페이스 식별자만 단방향 해시로 비교하며, 액세스·리프레시·ID 토큰 값은 판별에 사용하거나 별도로 저장·복사하지 않습니다.
5시간 한도 자동 시작 유지는 Codex 사용량을 실제로 소비하므로 배포 기본값은 꺼져 있습니다. 사용자가 켜면 앱은 model/list로 확인한 가장 가벼운 사용 가능 모델과 low effort를 선택하고, 각 연결마다 임시(ephemeral)·읽기 전용 App Server 스레드에서 산술 요청 하나를 보냅니다. 성공한 요청의 시작 시각을 로컬에 저장해 그로부터 5시간 뒤 다시 실행합니다. 자동 요청은 전체 연결 중 한 번에 하나만 실행하며, 다음 연결은 이전 연결의 요청 시작으로부터 최소 30분 뒤에 실행합니다. 실패한 연결도 30분 뒤 다시 시도하며 앱이 종료된 동안에는 실행하지 않습니다. 앱을 다시 열었을 때 여러 연결의 예정 시각이 지났더라도 한꺼번에 실행하지 않고 30분 간격으로 하나씩 처리합니다.
- macOS 13 Ventura 이상
- ChatGPT 계정
Node.js와 Codex CLI는 필요하지 않습니다. Codex CLI에 이미 로그인된 Mac에서는 해당 로그인을 기본 연결로 그대로 사용합니다. 다른 계정이나 같은 계정의 다른 워크스페이스는 앱의 계정 또는 워크스페이스 추가에서 로그인할 수 있으며, 각 연결의 인증 정보는 서로 분리된 앱 전용 CODEX_HOME에 저장됩니다.
추가 연결의 저장 위치는 macOS가 제공하는 Application Support 아래의 Codex Usage/Accounts/{UUID}/CodexHome입니다. App Store 빌드에서는 앱 샌드박스 컨테이너 안에 생성됩니다. 사용자가 지정한 워크스페이스 표시 이름은 로컬 계정 목록에 저장됩니다. 선택된 계정/워크스페이스 식별자는 단방향 해시와 짧은 보조 참조값으로만 보관하며, 앱은 인증 토큰 내용을 계정 간에 복사하지 않습니다.
Mac App Store 빌드는 App Sandbox 정책 때문에 다른 앱이 만든 ~/.codex 폴더를 자동으로 읽을 수 없습니다. 이 경우 최초 한 번 기존 Codex 로그인 연결을 눌러 .codex 폴더 접근을 승인합니다. 이것은 ChatGPT 재로그인이 아니며, 이후에는 보안 범위 북마크로 권한을 유지합니다.
저장소를 받은 뒤 다음 명령을 실행합니다.
./scripts/install.sh앱은 현재 사용자용 표준 앱 폴더인 ~/Applications/Codex Usage.app에 설치되고 즉시 실행됩니다. 이후에는 Finder의 응용 프로그램에서 평소 macOS 앱처럼 실행할 수 있습니다.
별도 제거 도구나 셸 명령이 필요하지 않습니다.
- 메뉴 바의 Codex Usage → 종료를 누릅니다.
- Finder에서
~/Applications를 엽니다. - Codex Usage를 휴지통으로 이동합니다.
로그인 시 자동 열기를 켰다면 삭제 전에 앱에서 끄거나, 시스템 설정 → 일반 → 로그인 항목에서 표준 방식으로 관리할 수 있습니다.
swift test
./scripts/build-app.sh현재 로그인된 Codex 계정까지 포함한 통합 테스트는 명시적으로 실행할 수 있습니다.
CODEX_LIVE_TEST=1 swift test --filter LiveCodexIntegrationTests빌드 결과는 dist/Codex Usage.app과 배포용 dist/Codex Usage.app.zip에 생성됩니다. iCloud 동기화 폴더가 앱 번들에 Finder 메타데이터를 다시 붙일 수 있으므로 배포·전달에는 서명 직후 만든 ZIP을 사용합니다. 빌드 시 현재 CPU 아키텍처에 맞는 공식 Codex 네이티브 런타임을 앱에 포함합니다. 로컬에 런타임이 없으면 빌드 시에만 고정 버전 패키지를 내려받고 SHA-512 무결성을 검사합니다. 최종 사용자의 Mac에서는 다운로드나 Node.js 설치가 일어나지 않습니다.
App Sandbox 권한을 포함한 App Store용 번들은 다음과 같이 확인할 수 있습니다.
APP_STORE_BUILD=1 ./scripts/build-app.sh기본 연결의 자동 갱신 주기는 앱의 기어 메뉴에서 선택하며 해당 Mac에만 저장됩니다. 추가 연결은 계속 15분마다 갱신됩니다. 개발 중 명령행에서 동일한 값을 지정하려면 아래 키에 30, 60, 300, 600, 1800, 3600 중 하나를 저장한 뒤 앱을 다시 실행합니다.
defaults write org.codeasy.CodexUsage SystemDefaultUsageRefreshIntervalSeconds -int 60이 명령은 개발 확인용 ad-hoc 서명을 사용합니다. 실제 App Store 제출 시에는 Apple Developer의 배포 인증서, 프로비저닝 프로파일 및 App Store Connect 메타데이터로 다시 서명·패키징해야 합니다.
사용량 조회 진단 로그는 계정 ID·이메일·토큰·CODEX_HOME 경로를 기록하지 않습니다. 문제를 재현할 때는 macOS 콘솔에서 하위 시스템 org.codeasy.CodexUsage, 범주 UsageRefresh로 필터링할 수 있습니다.
Codex app-server는 현재 실험적 인터페이스이므로 프로토콜이 바뀌면 앱 업데이트가 필요할 수 있습니다. 런타임은 앱 버전과 함께 고정되어 App Store 업데이트로 교체됩니다.
MIT
앱에 포함된 OpenAI Codex 런타임은 Apache License 2.0을 따릅니다. 자세한 내용은 THIRD_PARTY_NOTICES.md와 앱 번들의 라이선스 파일을 참고하세요.