Claude Code와 Codex의 사용 한도를 macOS 메뉴바에서 한눈에 보여주는 작은 플러그인입니다.
Token Ghost는 SwiftBar 위에서 동작합니다. SwiftBar가 메뉴바 앱이고, Token Ghost는 그 안에서 Claude/Codex 사용량을 읽어 표시하는 플러그인입니다.
🇺🇸 English guide: README.md
메뉴바 상단에는 Claude Code 현재 세션 사용률만 👻22% 형태로 표시됩니다.
클릭하면 전체 내역이 보입니다:
🧡 Claude
Current: 🟨🟨🟨⬜️⬜️⬜️⬜️⬜️ 36% (~9:10pm)
Weekly: 🟩🟩⬜️⬜️⬜️⬜️⬜️⬜️ 25% (~Jul 15 6pm)
Checked 3m ago
💙 Codex
5 Hour: 🟩⬜️⬜️⬜️⬜️⬜️⬜️⬜️ 12% (~8:28pm)
Weekly: 🟩🟩🟩⬜️⬜️⬜️⬜️⬜️ 35% (~Jul 17 6am)
From session log, 40m ago
프로그레스바는 사용률이 오를수록 초록 → 노랑 → 주황 → 빨강으로 채워집니다. 각 항목은 리셋 시각을 (~시각)으로 보여주고, 도구별로 값이 얼마나 최신인지도 표시합니다.
Token Ghost는 독립 앱이 아니라 SwiftBar 플러그인입니다:
SwiftBar = 메뉴바에 글자를 띄워주는 macOS 앱
Token Ghost = Claude/Codex 사용량을 읽어 메뉴에 표시하는 플러그인
Claude / Codex CLI = 사용 한도를 실제로 알고 있는 도구
즉, 터미널에서 Claude Code와 Codex가 이미 동작하는 상태여야 사용할 수 있습니다.
Claude — 짧은 인터랙티브 /usage 세션을 띄워서 읽습니다. Claude Code는 사용량 데이터를 파일로 남기지 않기 때문에, 짧게 TUI를 띄우는 것이 유일한 로컬 방법입니다. 부담을 줄이기 위해 이 캡처는 최대 15분에 한 번만 실행하고 그 사이에는 캐시를 보여주며, 메뉴에 값이 얼마나 오래됐는지 표시합니다. 주기는 TOKEN_GHOST_CLAUDE_TTL_MIN으로 바꾸거나, 메뉴의 Refresh로 즉시 새로 캡처할 수 있습니다.
Codex — Codex가 로컬 세션 로그(~/.codex/sessions/**/*.jsonl)에 남기는 구조화된 rate_limits 이벤트를 읽습니다. 터미널 자동화는 사용하지 않습니다. 이 로그는 Codex를 실제로 사용할 때만 갱신되므로:
- 메뉴에 데이터 나이(
From session log, 40m ago)를 표시하고, - 리셋 시각이 지난 윈도우는
0%와 함께 다음 리셋 예상 시각(보고된 리셋 시각에 창 길이를 더해 계산)을 표시합니다. 예:5 Hour: 0% (~3:18am). 다음 Codex 실행이 새 값을 기록하면 실제 값으로 갱신됩니다.
- macOS
- Python 3 (대부분의 개발용 Mac에 이미 있음)
- SwiftBar
- Claude Code CLI 로그인 — Claude 사용량 표시에 필요
- Codex CLI 로그인 — Codex 사용량 표시에 필요
Token Ghost는 대신 로그인해주지 않습니다. 각 CLI가 이미 동작하는지 확인하세요:
codex login status # Codex
claude # Claude Code: TUI가 열리며, 필요하면 /login으로 로그인터미널에 아래 한 줄을 붙여넣으세요 (꺾쇠 < > 없이):
curl -fsSL https://raw.githubusercontent.com/zoeymakes/token-ghost/v1.0.0/install.sh | bash설치 스크립트 동작:
SwiftBar 이미 있음 → Token Ghost 플러그인 설치
SwiftBar 없음 + Homebrew 있음 → brew로 SwiftBar 설치 후 플러그인 설치
SwiftBar 없음 + Homebrew 없음 → 플러그인만 설치, SwiftBar는 직접 설치
SwiftBar를 직접 설치해야 한다면 https://swiftbar.app 에서 받은 뒤 설치 명령을 다시 실행하세요.
cd token-ghost && ./install.shSwiftBar가 자동으로 열립니다. Plugin Folder를 물어보면, 설치 스크립트가 이미 SwiftBar가 감시하도록 설정된 폴더(없으면 ~/SwiftBarPlugins)에 설치해둡니다. 👻가 바로 안 보이면 SwiftBar → Refresh All을 눌러주세요. 처음 실행 시 macOS가 SwiftBar 실행·메뉴바 표시 권한을 물어볼 수 있으니 허용하세요.
- Refresh — 지금 즉시 새로 수집 (Claude 캐시 TTL 무시).
- Setup guide — 이 README 열기.
- Open Claude / Open Codex — 해당 앱 또는 웹사이트 열기.
환경 변수 (SwiftBar가 볼 수 있는 위치에 설정하거나 플러그인을 편집):
| 변수 | 기본값 | 효과 |
|---|---|---|
TOKEN_GHOST_CLAUDE_TTL_MIN |
15 |
Claude /usage 캡처 간격(분) |
TOKEN_GHOST_PLUGIN_DIR |
SwiftBar 설정 폴더 | 플러그인 설치 위치 |
~/.token-ghost/token_ghost.py --render-cache # 마지막 캐시 메뉴 출력
~/.token-ghost/token_ghost.py --collect # 수집 후 JSON 출력 (Claude는 TTL 적용)
~/.token-ghost/token_ghost.py --collect --force # Claude를 강제로 새로 캡처Token Ghost는 비밀번호, API Key, Access Token, 계정 인증정보를 저장하지 않습니다. 이미 설치된 claude, codex 도구에서 사용량만 읽어, 사용률과 리셋 시각만 아래에 캐시합니다:
~/.cache/token-ghost/cache.json
curl -fsSL https://raw.githubusercontent.com/zoeymakes/token-ghost/main/uninstall.sh | bash캐시까지 지우려면, 다운로드한 폴더에서:
./uninstall.sh --with-cache<SwiftBar 플러그인 폴더>/token-ghost-menu.5m.py
~/.token-ghost/token_ghost.py
~/.token-ghost/README.md
~/.cache/token-ghost/cache.json
- 독립
.app이 아니라 SwiftBar 플러그인입니다. - Codex 값은 Codex를 실제로 사용할 때만 갱신됩니다. 대신 데이터 나이를 표시하고, 리셋이 지난 윈도우는 예상 리셋 시각의 추정값으로 표시합니다.
- Claude 값은 짧은 인터랙티브 캡처로 얻으며, 캡처 사이(15분 TTL)에는 캐시된 값과 나이를 보여줍니다.
- SwiftBar 메뉴는 텍스트 기반이라 프로그레스바는 컬러 사각형으로 표시합니다.
MIT — LICENSE 참고.