AI Battery

Claude와 Codex 구독을 최대한 활용하세요.

aibattery.dev

macOS 메뉴 바에서 Claude Code 및 OpenAI Codex 계정의 속도 제한(rate limits), 컨텍스트 상태(context health), 토큰 사용량을 한 화면에서 모니터링합니다.

macOS

License

CI

GitHub stars

Downloads

📦 설치

brew tap KyleNesium/tap
brew install --cask aibattery

curl -sL https://github.com/KyleNesium/AIBattery/releases/latest/download/AIBattery.zip -o /tmp/AIBattery.zip && ditto -x -k /tmp/AIBattery.zip /Applications && xattr -cr /Applications/AIBattery.app && open /Applications/AIBattery.app

Releases에서 다운로드:</details>

1. AIBattery.dmg를 열고 AI Battery를 Applications 폴더로 드래그합니다.
2. Applications에서 실행합니다 — macOS는 첫 실행 시 차단할 수 있습니다.
3. **시스템 설정(System Settings) → 개인 정보 보호 및 보안(Privacy & Security)**으로 이동하여 아래로 스크롤한 후 **어쨌든 열기(Open Anyway)**를 클릭합니다.

[!TIP]
만약 macOS가 앱이 손상되었다고 표시하면, xattr -cr /Applications/AIBattery.app을 실행한 다음 다시 시작하세요.

git clone https://github.com/KyleNesium/AIBattery.git && cd AIBattery
./scripts/build-app.sh
open .build/AIBattery.app

**macOS 13+**와 Claude Code 및/또는 Codex CLI가 필요합니다. 더 자세한 정보는 aibattery.dev를 참조하세요.

🔄 업데이트(Update)

AI Battery는 하루에 한 번 업데이트 여부를 확인합니다. 사용 가능한 업데이트가 있으면 헤더 아래에 배너가 나타납니다. 이를 해제하면, 설정을 통해 ⚙️ 기어가 업데이트 배지를 가지게 되며, 설치할 때까지 유지됩니다. 업데이트 확인(Check for Updates), 설치(Install), 그리고 앱 버전과 함께 **릴리스 노트(Release notes)**는 설정 → 정보(Settings → About)에서 확인할 수 있습니다.

🔐 인증(Authentication)

두 제공업체 모두에 대해 PKCE를 사용한 OAuth 2.0을 지원합니다 — 이는 Claude Code와 Codex CLI가 사용하는 것과 동일한 프로토콜입니다. 최대 3개의 Claude 계정(별도 조직) 및 3개의 Codex 계정(ChatGPT 로그인)을 나란히 지원합니다.

어떤 계정을 보고 있나요? 헤더는 계정 칩입니다. 제공업체의 브랜드 마크가 자체 색상으로 표시되고, 그 뒤에 계정 ID(설정에서 지정한 이름 또는 그렇지 않으면 로그인 이메일(Codex) 또는 워크스페이스 이름(Claude))가 표시됩니다. 만약 아무것도 설정하지 않았다면

• 클럭 스큐(clock-skew) 문제를 방지하기 위해 5분 버퍼로 세션이 자동 새로고침됩니다.
• 일시적인 서버 오류는 자동으로 재시도됩니다.
• 계정별로 macOS Keychain에 리프레시 토큰이 저장됩니다 (Claude Code 자격 증명과는 별개). 액세스 토큰은 메모리에만 보관됩니다.
• 오류 메시지는 구체적입니다 — 만료된 코드, 유효하지 않은 코드, 서버 오류 및 네트워크 오류 각각 명확한 설명을 받습니다。

AI Battery는 노타라이즈(notarized)되지 않았습니다 — 이 프로젝트 뒤에는 Apple Developer 라이선스가 없기 때문에 macOS는 이를 미확인으로 처리합니다. 첫 실행 시 두 가지 프롬프트가 나타날 수 있습니다:

• Gatekeeper 차단 — macOS가 앱 실행을 막습니다. 해결 방법: 시스템 설정 → 개인 정보 보호 및 보안 → 허용 (설치(Install) 참고).
• 키체인 접근 — 이 앱은 OAuth 리프레시 토큰을 macOS 키체인에 저장합니다 (계정당 하나의 항목). Apple의 암호화된 자격 증명 저장소입니다. 항상 허용을 클릭하세요. 프롬프트는 인앱 업데이트 후 새로운 바이너리가 다른 ad-hoc 서명을 가졌기 때문에 한 번 다시 나타날 수 있습니다.

Gatekeeper 프롬프트는 일회성입니다. 키체인 프롬프트는 첫 실행 시와 각 인앱 업데이트 후에 한 번씩 나타납니다.

📐 지표 (Metrics)

최소한의 API 호출은 Claude Code 계정 메타데이터를 사용하여 5시간 및 7일 사용량을 읽어옵니다(사용 가능한 경우 레거시 헤더 폴백). Codex 계정은 ChatGPT 사용량 엔드포인트를 읽고, 최신 Codex CLI 세션 로그로 폴백합니다. 로컬 JSONL 세션 로그(~/.claude/projects, ~/.codex/sessions)는 토큰 수와 컨텍스트 상태를 제공하며 — 절대 메시지 내용을 포함하지 않습니다. 아래의 모든 항목 — 막대, 인사이트(Insights), 비용, 프로젝트(Projects), 상태 점 — 은 활성 계정의 제공업체를 따릅니다 (Codex는 긴 기간을 **주간(Weekly)**으로 표시합니다). 하단의 사용량(Usage) 링크는 사용자의 제공업체 사용량 대시보드를 엽니다.

탭 선택기는 어떤 지표가 ✦ 아이콘 색상을 결정하는지 선택합니다 (두 개 이상의 계정이 있는 경우 메뉴 바에는 각 계정의 최악의 기간이 표시됩니다 — 전체 계정 한눈에 보기(All accounts at a glance) 참고):

[!NOTE]
5시간 및 7일 막대는 Anthropic API 슬라이딩-윈도우 헤더에서 가져옵니다. 이는 다른 플랜 사용량 의미론과 재설정 타이밍을 사용하는 Claude Code의 /usage와 다를 수 있습니다.

자동 모드(Auto mode): 탭 옆의 (A) 버튼을 클릭하세요. 활성화되면 파란색으로 빛나며 가장 높은 백분율을 가진 지표를 자동으로 선택하여 메뉴 표시줄에 항상 가장 중요한 한계치를 보여줍니다. 수동 모드로 돌아가려면 아무 탭이나 클릭하면 됩니다. 자동 모드가 비활성화되고 한 번의 동작으로 전환됩니다.

🧠 컨텍스트 상태(Context Health)

컨텍스트 상태를 보여줍니다. 가장 최근의 5개 세션에 대한 컨텍스트 상태를 확인하세요. < 1/5 > 화살표로 탐색하거나 좌우로 스와이프하세요. 오래된 세션(유휴 시간 > 30분)은 황갈색 "Idle" 배지를 표시합니다.

각 세션은 다음을 표시합니다: 프로젝트 이름 (project name) · 깃 브랜치 (git branch) · 지속 시간 (duration) · 마지막 활동 시간 (last active time).

백분율은 모델의 전체 컨텍스트 창(full context window) 대비 상대적입니다. 현재 Claude 모델의 경우 1M 토큰, Codex를 통한 GPT-5 계열 모델의 경우 약 258K 토큰을 사용합니다 (TokenHealthConfig). 최상의 결과를 얻으려면 최소 20–40%는 여유 공간을 유지하세요. 컨텍스트가 95%를 초과하면 Anthropic이 자동 압축(auto-compaction) 문서를 처리합니다.

컨텍스트를 Claude의 단기 기억으로 생각하세요. 모든 메시지, 파일 읽기, 도구 호출(tool call), 응답은 200K 토큰 창에 축적됩니다. 대화 턴 사이에 아무것도 폐기되지 않습니다. 가득 차면, Claude Code가 자동 압축(auto-compacts)을 수행하여 세션을 몇 개의 단락으로 요약하고 나머지를 지웁니다. 이 요약은 손실성(lossy)이 있습니다: 파일 내용, 특정 지침, 미묘한 결정 등이 압축됩니다. Claude는 계속 작동하지만, 실제 대화가 아닌 요약본을 기반으로 합니다.

긴 대화 (15턴 이상) — 턴(turn) 사이에 아무것도 버려지지 않습니다. 사용자의 메시지, Claude의 응답, 도구 호출 및 결과가 모두 누적됩니다. 약 15턴이 지나면 창은 오래된 기록으로 가득 차고, Claude는 매번 이 기록을 읽게 되어 응답 속도가 느려지고, 품질이 저하되며, 오래된 컨텍스트에 토큰 예산을 소모하게 됩니다.

높은 입력:출력 비율 (20:1 이상) — 출력되는 것보다 입력되는 토큰(파일 읽기, 오류 로그, 도구 결과 등)이 더 많습니다. 예를 들어, 대용량 파일 5개를 읽으면 Claude가 한 번만 참조할 수 있는 컨텍스트에 수천 개의 토큰이 쌓입니다. 이 데이터는 세션 나머지 기간 동안 창에 남아 다음 모든 턴에서 토큰을 소모하며 유용한 작업 공간을 줄어들게 합니다.

출력 없는 세션 (Zero-output session) — 여러 턴이 있지만 출력되는 토큰이 없습니다. 오류 루프나 대화가 정체되었음을 나타낼 수 있습니다.

빠른 토큰 소모 (Rapid token consumption) — 매우 짧은 세션임에도 불구하고 토큰 사용량이 높습니다. 대용량 파일이나 긴 붙여넣기가 컨텍스트 창을 빠르게 채우고 있을 수 있습니다.

[!TIP]
주황색 또는 빨간색 경고가 뜰 때:

1. /compact를 실행하여 요약을 프로젝트 메모리에 저장합니다.
2. 주요 결정 사항은 CLAUDE.md에 보관하세요 — 매 세션마다 자동으로 로드됩니다.
3. 동일한 디렉터리에서 새 터미널을 시작하고 중단했던 지점부터 다시 시작합니다.

⚙️ 설정 (Settings)

계정 보기의 헤더에 있는 ⚙️ 또는 개요 푸터의 **설정(Settings)**을 클릭하여 다음을 구성할 수 있습니다: