CodexBar 딥다이브
— "내 AI 코딩 토큰이 얼마나 남았나"를 메뉴바에: 로그인 없이 57개 프로바이더 사용량을 긁어오는 Swift 6 앱

1프로젝트 한줄 요약

이 저장소가 대체 무엇인가.

CodexBar(제작자 Peter Steinberger, PSPDFKit 창업자)는 Codex·Claude Code·Cursor·Copilot 등 AI 코딩 구독 도구의 "남은 한도"를 메뉴바 아이콘 하나로 보여주는 macOS 앱이다. 핵심 원칙은 "로그인 없음(no login)" — 새 계정을 만들거나 비밀번호를 넣게 하지 않고, 이미 내 컴퓨터에 저장돼 있는 인증 정보(OAuth 토큰 파일·브라우저 쿠키·CLI 자격증명)를 그대로 재사용해 각 제공사의 사용량 API를 대신 호출한다.

코드상 버전은 0.41.0(빌드 100)이며 라이선스는 관대한 MIT(저작권 2026 Peter Steinberger, 웹사이트 codexbar.app). 실행에는 macOS 14(Sonoma) 이상이 필요하고, Dock 아이콘 없이 메뉴바에만 사는 LSUIElement 방식이다. 별점은 약 15.7k로, 개발자용 소도구치고는 대단히 높다. CHANGELOG가 161KB에 달할 만큼 거의 매일 릴리스되는 초활발 프로젝트다.

2왜 주목받는가

트렌딩 이유와, 흔한 "사용량 추적기"와의 결정적 차이.

① 로그인이 필요 없다 — 기존 세션을 재사용한다

보통의 사용량 대시보드는 "우리 서비스에 로그인하라"고 요구한다. CodexBar는 정반대다. 이미 내 기기에 있는 자격증명을 그대로 빌려 쓴다 — Codex는 ~/.codex/auth.json의 OAuth 토큰, Claude는 ~/.claude/.credentials.json이나 키체인 항목, 웹 대시보드는 Safari·Chrome·Firefox 쿠키를 읽는다. README는 "비밀번호를 저장하지 않는다"고 못박고, 파일시스템을 뒤지지 않고 알려진 소수의 경로만 해당 기능을 켰을 때에만 읽는다고 강조한다.

② 57개 프로바이더를 하나로 묶는다

Codex·OpenAI·Claude·Cursor·Gemini·Copilot·Grok·GroqCloud·z.ai·MiniMax·Kiro·Zed·Vertex AI·AWS Bedrock… README가 나열하는 제공사는 약 57~60개다. 이렇게 많은 AI 코딩 도구의 한도를 한 앱에서 보는 경쟁 제품은 사실상 없다. CHANGELOG는 Thanks @기여자 크레딧으로 가득해, 커뮤니티가 새 프로바이더를 계속 밀어넣는 구조임을 보여준다.

③ API를 안 치고도 비용을 계산한다 (ccusage 방식)

CodexBar는 라이브 한도(API 조회)와 별개로, 로컬 로그 파일만 읽어 "지금까지 토큰을 얼마나 썼고 달러로 얼마인지"를 계산하는 비용 스캐너를 내장한다. ~/.codex/sessions/**/*.jsonl과 ~/.claude/projects/**/*.jsonl을 스트리밍으로 훑어 토큰 수를 세고, 내장 모델별 단가표로 곱한다. README는 이 아이디어가 유명한 ccusage(MIT)에서 왔다고 밝힌다. 네트워크 없이도 동작하는 셈이다.

④ 스크립트가 아니라 '진짜 제품'이다

메뉴바 앱이라고 얕볼 규모가 아니다. Swift 소스 784개 파일, 약 18.7만 줄이 6개의 SPM 타깃으로 나뉘고, Sparkle 자동업데이트(EdDSA 서명)·WidgetKit 위젯·21개 언어 현지화(RTL 포함)·프로바이더 장애 폴링·macOS Tahoe 메뉴바 아이콘 복구 경로까지 갖췄다. 심지어 Linux까지 빌드되는 크로스플랫폼 CLI(codexbar)와 Homebrew·AUR 패키지도 제공한다. "네이티브 유틸리티를 어디까지 다듬을 수 있나"의 상한선을 보여준다.

3기술 스택 전체 지도

무엇으로 만들어졌나 — 계층별로. (Package.swift·Package.resolved에서 실제 확인)

언어 & 빌드 시스템

SPM 의존성 (선언값 → 잠금값)

주목할 점: 의존성 목록이 짧고 대부분 애플 공식(swift-crypto·swift-log·swift-asn1)이거나 제작자 본인 라이브러리(Commander·SweetCookieKit)다. 무거운 서드파티 프레임워크에 기대지 않고 플랫폼 API를 직접 쓰는 취향이 드러난다.

SPM 타깃 6개 (한 저장소, 여러 산출물)

도구 & CI

SwiftFormat + SwiftLint로 스타일을 강제하고(make check), CI(.github/workflows/ci.yml)는 lint를 ubuntu-24.04에서, macOS 테스트를 macos-15-intel 러너에서 Xcode 26.3/26.2로 돌린다. 별도 워크플로 release-cli.yml(19KB)은 macOS·Linux × glibc·musl × arm64·x86_64 조합으로 CLI 타르볼을 굽는다. 이 정도 릴리스 매트릭스는 메뉴바 앱에서 보기 드물다.

4아키텍처 심화 분석

"메뉴바 숫자"가 어디서 어떻게 오는가.

전체 그림 — fetch → store → UI

공식 docs/architecture.md가 그리는 데이터 흐름은 단순명료하다: 백그라운드 새로고침 → 프로바이더 프로브가 사용량을 가져옴 → 중앙 저장소(UsageStore)에 반영 → 메뉴/아이콘/위젯이 그림. 복잡함은 전부 "프로바이더별로 어디서 어떻게 긁어오나"에 숨어 있다.

메뉴바 만들기 — NSStatusItem

메뉴바 아이콘은 StatusItemController(@MainActor final class … : NSObject, NSMenuDelegate)가 관리한다. 프로바이더가 여러 개면 statusItems: [UsageProvider: NSStatusItem]처럼 아이콘도 여러 개 만든다. 실제 생성 코드는 이렇게 생겼다:

private static func makeStatusItem(
    statusBar: NSStatusBar,
    identity: StatusItemIdentity,
    defaults: UserDefaults,
    legacyDefaultItemIndex: Int?)
    -> NSStatusItem
{
    let item = statusBar.statusItem(withLength: NSStatusItem.variableLength)
    item.autosaveName = identity.autosaveName          // 위치 기억
    if let button = item.button {
        button.imageScaling = .scaleNone               // 1:1 렌더(선명한 템플릿 아이콘)
        button.setAccessibilityIdentifier(identity.accessibilityIdentifier)
        button.toolTip = title
    }
    return item
}

autosaveName으로 사용자가 옮긴 아이콘 위치를 기억하고, imageScaling = .scaleNone으로 리샘플링 없이 선명하게 그린다. StatusItemController는 메뉴·애니메이션·스위처 등으로 나뉘어 약 120개의 StatusItemController+*.swift 확장 파일로 쪼개져 있다(한 파일이 74KB에 이르기도 한다). macOS Tahoe가 NSStatusItem.isVisible 동작을 바꿔도 살아남도록 방어 코드까지 들어 있다.

Codex 사용량 가져오기 — OAuth HTTP

가장 기본 경로는 ~/.codex/auth.json의 OAuth 토큰을 읽어, ChatGPT 백엔드의 사용량 엔드포인트를 직접 부르는 것이다:

public static func fetchUsage(accessToken: String, accountId: String?, …)
    async throws -> CodexUsageResponse
{
    var request = URLRequest(url: Self.resolveUsageURL(env: env))
    request.httpMethod = "GET"
    request.timeoutInterval = 30
    request.setValue("Bearer \(accessToken)", forHTTPHeaderField: "Authorization")
    request.setValue("application/json", forHTTPHeaderField: "Accept")
    if let accountId, !accountId.isEmpty {
        request.setValue(accountId, forHTTPHeaderField: "ChatGPT-Account-Id")
    }
    let response = try await ProviderHTTPClient.shared.response(for: request)
    switch response.statusCode {
    case 200...299: return try JSONDecoder().decode(CodexUsageResponse.self, …)
    case 401, 403: throw CodexOAuthFetchError.unauthorized
    …
    }
}

엔드포인트는 GET https://chatgpt.com/backend-api/wham/usage, 헤더는 Authorization: Bearer <token>. 응답의 primary_window는 세션 레인, secondary_window는 주간 레인으로 매핑된다. OAuth가 막히면 codex -s read-only -a untrusted app-server를 띄워 JSON-RPC(stdin/stdout)로 account/rateLimits/read를 부르는 CLI 경로로 폴백한다.

Claude 사용량 가져오기 — 로컬 JSONL 파싱

라이브 한도와 별개로, 비용 스캐너는 ~/.claude/projects/**/*.jsonl 로그를 직접 읽어 토큰을 센다. 핵심 파싱은 이렇게 단순하다:

guard let message = obj["message"] as? [String: Any] else { return }
guard let model   = message["model"] as? String else { return }
guard let usage   = message["usage"] as? [String: Any] else { return }

let input       = max(0, toInt(usage["input_tokens"]))
let cacheCreate = max(0, toInt(usage["cache_creation_input_tokens"]))
let cacheRead   = max(0, toInt(usage["cache_read_input_tokens"]))
let output      = max(0, toInt(usage["output_tokens"]))

let cost = CostUsagePricing.claudeCostUSD(          // 토큰 × 모델별 단가
    model: model, inputTokens: input,
    cacheReadInputTokens: cacheRead,
    cacheCreationInputTokens: cacheCreate,
    outputTokens: output, pricingDate: timestamp, …)

영리한 부분은 파일을 통째로 메모리에 올리지 않는다는 것. CostUsageJsonl이 로그를 256KB 청크로 스트리밍하며 개행(0x0A)으로 잘라 한 줄씩 넘기고, 바이트 오프셋을 기억(resume)해 다음번엔 새로 추가된 바이트만 읽는다. 스트리밍 중복 청크는 message.id + requestId로 dedup한다. 거대한 히스토리도 값싸게 훑는 비결이다.

동시성 — Swift 6 엄격 모드를 실전 규모로

중앙 상태는 @MainActor @Observable final class UsageStore 하나다. UI가 건드리는 상태는 전부 메인 액터에 묶여 데이터 레이스가 원천 차단된다. 반대로 무거운 외부 I/O는 전용 actor로 분리한다 — actor CodexCLISession, actor ClaudeCLISession, actor ClaudeWebBrowserFetchGate 등. 소스 전체에 async가 1,103회, @MainActor가 700회 등장한다.

@MainActor
@Observable
final class UsageStore {
    var isRefreshing = false        // 단일화(single-flight) 가드
    …
    func refresh(forceTokenUsage: Bool = false) async { … }
}

5디렉토리 구조 해부

784개 파일이 어디에 어떻게 놓였나.

꼭 알아둘 핵심 파일

디렉토리만 봐도 설계 의도가 보인다. 한 프로바이더 = 한 폴더(Providers/Codex/, Providers/Claude/…)로 격리돼 있어, 새 도구를 추가할 때 다른 코드를 건드리지 않는다. 문서(docs/)도 프로바이더별로 약 50개가 따로 있다.

6학습 포인트 (기술별)

이 코드베이스에서 무엇을 훔쳐 배울 수 있나.

① 네이티브 macOS 메뉴바 앱 설계

NSStatusItem(variableLength·autosaveName·템플릿 아이콘 1:1 렌더), Dock 없는 에이전트 앱(LSUIElement), 그리고 AppKit 메뉴바 + SwiftUI 설정 화면을 한 앱에 섞는 하이브리드 패턴. SwiftUI Settings 씬을 살리려고 숨겨진 1×1 WindowGroup으로 생명주기를 유지하는 트릭까지 배운다.

② Swift 6 엄격 동시성 — 대규모 적용 사례

교과서 예제가 아니라 18만 줄 규모에서 어떻게 액터를 나누는가를 본다. UI 상태는 @MainActor로 모으고, 외부 프로세스/네트워크 I/O는 전용 actor로 격리하며, 새로고침은 단일화 가드로 한 번에 하나만 돈다. "부수효과를 순수 함수 밖으로 밀어내는" 테스트 친화 설계도 실물로 확인한다.

③ 로컬 텔레메트리 파싱 — 값싸게, 증분으로

대용량 *.jsonl을 청크 스트리밍으로 읽고, 바이트 오프셋 resume으로 새 데이터만 처리하며, message.id 기반으로 중복을 제거하고, 모델별 단가표로 토큰을 달러로 환산한다. ccusage의 비용 모델을 Swift로 재구현한 깔끔한 표본이다.

④ 외부 CLI를 프로그램으로 몰기

두 가지 상반된 방식을 한 레포에서 본다 — (a) codex app-server를 JSON-RPC over stdin/stdout으로 구동(구조적 프로토콜), (b) 대화형 TUI인 claude를 PTY(가상 터미널)로 자동화하고 /usage를 쳐서 나온 화면을 ANSI 코드 제거 후 파싱(비구조적 출력 긁기). 타임아웃·자식 프로세스 강제 종료 같은 안전장치도 포함이다.

⑤ 비밀번호 없이 인증하기

OAuth 토큰을 디스크에서 재사용하고, 브라우저 쿠키를 SweetCookieKit + swift-crypto + 키체인으로 복호화하며(Chromium "Safe Storage"), Copilot은 디바이스 플로우를 쓴다. 소스가 막히면 다음 소스로 우아하게 폴백하는 체인 설계가 핵심이다.

⑥ 제품 수준 배포 파이프라인

SPM을 배포 가능한 .app의 주 빌드 시스템으로 쓰고, Sparkle의 EdDSA 서명 + appcast로 자동업데이트하며, WidgetKit 위젯은 앱 그룹 JSON 스냅샷으로 데이터를 넘긴다. macOS·Linux를 아우르는 CLI 릴리스 매트릭스, SwiftFormat/SwiftLint, 21개 언어 현지화까지 — "1인 개발자가 어디까지 자동화하나"를 본다.

7하드웨어/시스템 요구사항

돌리려면 / 빌드하려면 무엇이 필요한가.

8직접 해볼 수 있는 실습 과제

읽기만 하면 안 남는다 — 난이도별로 손을 움직여 보자.

9관련 기술 심화 학습 로드맵

이 레포를 온전히 읽으려면 — 5주 코스.

10핵심 키워드 사전

문서에 나온 용어를 한 번에.

11참고 링크

더 깊이 파고들 곳.