CodexBar는 작은 편의 앱처럼 보인다. Codex, Claude, Cursor, Gemini, Copilot을 비롯한 AI 코딩 도구의 한도를 macOS 메뉴 막대에 띄워 언제 초기화되는지 알려준다. 나는 **v0.41.0, 커밋 a83a83f**의 소스를 읽었고, 더 흥미로운 이야기는 메뉴 막대가 아니라 그 아래의 정규화 계층에 있었다.
CodexBar가 푸는 문제는 “진행률 막대를 그리는 것”이 아니다. 진짜 문제는 AI 코딩 도구마다 서로 다른 종류의 한도를 드러낸다는 점이다. 어떤 프로바이더는 OAuth 사용량 구간을 제공한다. 다른 프로바이더는 브라우저 쿠키가 필요하다. API 키 잔액을 주는 곳도 있고, CLI나 로컬 로그만 있는 곳도 있다. 초기화 주기는 시간, 주, 월 단위로 제각각이고, 크레딧을 파는 곳도, 장애 상황을 알리는 곳도, 한도에 부딪힐 때까지 쓸 만한 정보를 거의 주지 않는 곳도 있다.
그래서 CodexBar의 실제 아키텍처는 프로바이더 사용량 측정 런타임이다. 메뉴 막대는 눈에 보이는 표면일 뿐이다. 핵심은 프로바이더 식별자, 디스크립터, 가져오기 전략, 앱 훅을 선별해 구성하고, 서로 맞지 않는 벤더 신호를 공통 사용량 스냅샷으로 바꾸는 카탈로그다.
무엇이며, 어디에 자리하는가?
CodexBar는 번들 CLI를 포함한 macOS 14+ 메뉴 막대 앱이다. README는 사용자에게 제공하는 기능을 잘 설명한다. 수십 개 AI 코딩 프로바이더의 세션 한도, 주간 한도, 크레딧, 지출, 초기화 카운트다운, 프로바이더 상태를 추적한다.
하지만 코드에서 “수십 개 프로바이더”는 임의의 플러그인을 뜻하지 않는다. 프로바이더 식별자는 유한한 Swift enum에서 시작한다. UsageProvider는 codex부터 clawrouter까지 지원하는 case를 열거한다(Providers.swift:5-63). 이것이 첫 번째로 중요한 제약이다. CodexBar는 런타임에 아무 프로바이더 문자열이나 나타날 수 있는 범용 마켓플레이스가 아니다. 선별된 카탈로그다.
이 카탈로그 설계는 의도적이다. 각 프로바이더 항목에는 디스크립터가 하나씩 붙고, 그 디스크립터가 메타데이터, 브랜딩, 토큰 비용 동작, 가져오기 계획, CLI 메타데이터라는 프로바이더 계약을 소유한다(ProviderDescriptor.swift:13-35). Codex 디스크립터가 좋은 예다. 표시 라벨, 대시보드 URL, 상태 URL, 아이콘, 토큰 비용 설정, 소스 모드, 가져오기 파이프라인, CLI 버전 감지기를 한곳에서 채운다(CodexProviderDescriptor.swift:7-40).
이 구조는 CodexBar를 쓸모 있는 범주에 놓는다. LLM 게이트웨이도, 비용 라우터도 아니다. 사용자와 모델 사이의 요청 경로에 자리하지 않는다. 도구 옆에 앉아 각 프로바이더가 노출하는 사용량 근거를 읽고, 보이지 않던 초기화 구간을 운영 가능한 정보로 바꾼다.
프로바이더 디스크립터가 중심이다
CodexBar를 가장 명확하게 읽는 방법은 네 계층으로 보는 것이다.
| 계층 | 소유하는 것 | 소스 |
|---|---|---|
| 프로바이더 식별자 | 지원하는 프로바이더의 유한한 카탈로그 | UsageProvider |
| 프로바이더 디스크립터 | 라벨, URL, 기능, 브랜딩, 가져오기 계획, CLI 이름 | ProviderDescriptor |
| 가져오기 전략 파이프라인 | OAuth, CLI, 웹, API 토큰, 로컬 프로브, 대시보드 경로를 시도하는 방법 | ProviderFetchPipeline |
| 앱 구현 | 설정, 로그인, 표시, 메뉴 항목, 프로바이더별 UI 훅 | ProviderImplementation |
디스크립터 레지스트리는 이를 명확히 보여준다. ProviderDescriptorRegistry는 각 UsageProvider 항목을 구체적인 디스크립터 싱글턴에 매핑한다(ProviderDescriptor.swift:55-113). 그런 다음 UsageProvider.allCases를 순회하며 부트스트랩하고, 디스크립터가 하나라도 없으면 실패한다(ProviderDescriptor.swift:114-121).
이것이 유지보수 계약이다. 프로바이더를 추가할 때 가져오기 모듈 하나만 넣으면 끝나지 않는다. 프로바이더 식별자, 디스크립터, 전략, 앱 구현, 아이콘, 설정, 테스트를 추가해야 한다. 동적 플러그인 인터페이스보다 무겁지만, 그 대신 안정된 제품 표면을 얻는다. 앱은 어떤 프로바이더가 존재하는지, 무엇이 주요 프로바이더인지, 어떤 것이 크레딧을 지원하는지, 상태 URL이 있는지, 어떤 소스 모드를 허용하는지, 어떤 CLI 별칭이 어느 프로바이더를 가리키는지 알 수 있다.
가져오기는 거대한 switch 하나가 아니라 전략 파이프라인이다
CodexBar의 형태가 제값을 하는 곳은 가져오기 경로다. 프로바이더 전략에는 네 가지 필수 요소가 있다. id, kind, 가용성 검사, 가져오기 함수, 폴백 정책이다(ProviderFetchPlan.swift:188-194). 전략 종류는 복잡한 현실을 감당할 만큼 넓다. CLI, 웹, OAuth, API 토큰, 로컬 프로브, 웹 대시보드가 있다(ProviderFetchPlan.swift:179-186).
파이프라인은 컨텍스트에서 전략 목록을 결정하고, 하나씩 검사하며, 각 시도를 기록한다. 첫 성공 결과를 반환하거나, 해당 전략이 폴백을 허용하면 다음으로 넘어간다(ProviderFetchPlan.swift:220-275). 이 시도 로그는 중요하다. “왜 내 Claude 미터가 최신 상태가 아니지?“는 단순한 예외가 아니라 제품이 답해야 할 질문이기 때문이다.
흥미로운 점은 전략 순서가 런타임과 소스 모드 모두에 따라 달라질 수 있다는 것이다. Codex는 단순하게 나뉜다. 자동 모드에서는 앱과 CLI 모두 OAuth를 먼저 시도한 다음 CLI를 시도한다. 명시적 모드에서는 OAuth, 웹, CLI 중 하나로 좁혀진다(CodexProviderDescriptor.swift:43-75). Claude는 더 복잡하다. 소스 플래너를 실행하고, 계획된 단계를 Admin API, OAuth, 웹, CLI 전략에 매핑한다(ClaudeProviderDescriptor.swift:45-77).
이것이 핵심 설계 결정이다. CodexBar는 모든 프로바이더가 같은 종류의 진실을 가졌다고 가장하지 않는다. 각 프로바이더에 통제된 전략 목록을 주고, 그 결과를 같은 형태로 맞춘다.
공통 형태는 사용량 스냅샷이다
성공한 전략은 모두 ProviderFetchResult를 반환한다. 이 결과에는 UsageSnapshot, 선택적 크레딧, 선택적 대시보드 데이터, 소스 라벨, 성공한 전략의 ID/kind가 담긴다(ProviderFetchPlan.swift:97-141). 전략은 이 필드들을 일관되게 감싸는 헬퍼를 사용한다(ProviderFetchPlan.swift:196-210).
여기가 압축 단계다. Claude OAuth, Codex CLI, OpenAI 대시보드 스크레이핑, 로컬 비용 스캔, API 키 잔액은 입력 단계에서 모두 복잡할 수 있다. 그다음 메뉴 막대와 CLI가 보는 것은 스냅샷, 크레딧, 대시보드, 상태, 소스 라벨이다.
그래서 “메뉴 막대 앱”은 CodexBar를 설명하기에 너무 작다. UI는 정규화 경계의 다운스트림에 있다.
앱 계층은 훅 경계다
CodexBar는 앱 쪽 프로바이더 구현을 코어 디스크립터와 분리한다. 프로토콜은 이를 명시한다. 앱 쪽 구현은 데이터와 동작 디스크립터를 반환하고 UI는 앱이 소유하며, 식별자 필드는 프로바이더별로 격리한다(ProviderImplementation.swift:4-9).
훅 목록은 길지만 경계가 분명하다. 표시, 설정 관찰, 가용성, 소스 라벨, 소스 모드, 런타임, 설정 토글, 설정 필드, 메뉴 항목, 로그인 액션, 로그인 흐름이다(ProviderImplementation.swift:13-83). 앱에는 모든 UsageProvider를 구체적인 앱 구현에 빠짐없이 매핑하는 자체 레지스트리도 있다(ProviderImplementationRegistry.swift:14-73).
이 분리가 중요한 이유는 프로바이더 코드가 서로 합쳐져서는 안 되는 두 가지 일을 맡기 때문이다.
- 코어: 사용량 데이터를 얻고 정규화하는 방법을 안다.
- 앱: 설정, 로그인, 메뉴 액션, 프로바이더별 표시 방법을 안다.
이 둘이 앱의 거대한 switch 문 하나에 들어 있었다면, 처음에는 프로바이더를 더 빨리 추가할 수 있어도 나중에는 더 힘들어진다. CodexBar는 이미 그 방식이 고통스러워질 임계점을 넘어섰다.
CLI는 별도의 제품 모델이 아니다
CodexBar는 패키지 안에 CLI 실행 파일(CodexBarCLI)을 포함한다(Package.swift:27-31). 중요한 점은 CLI가 완전히 별개의 프로바이더 세계를 유지하지 않는다는 것이다.
프로바이더 CLI 이름과 별칭은 디스크립터에서 파생된다. ProviderDescriptorRegistry.cliNameMap은 모든 디스크립터를 순회하고 descriptor.cli.name과 별칭을 프로바이더 ID에 매핑한다(ProviderDescriptor.swift:156-166). CLI 명령은 프로바이더 입력을 해석할 때 이 맵을 사용하고(CLICacheCommand.swift:30-32), 렌더러는 같은 디스크립터 레지스트리에서 표시 메타데이터를 읽는다(CLIRenderer.swift:12-20).
가져오기 경로도 공유한다. CLI 사용량 명령은 runtime: .cli로 ProviderFetchContext를 만들고 fetchProviderUsage를 호출한다(CLIUsageCommand.swift:408-425). 헬퍼는 디스크립터를 결정하고 descriptor.fetchOutcome(context:)를 반환한다(CLIHelpers.swift:186-198). macOS 앱의 새로고침 경로도 가져오기 컨텍스트를 만들고 디스크립터의 가져오기 결과를 호출한다(UsageStore+Refresh.swift:182-192).
따라서 CLI는 “프로바이더 사용량”의 두 번째 구현이 아니다. 같은 디스크립터와 가져오기 결과 진입점 위에 놓인 또 하나의 표면이다.
트레이드오프: 임의의 플러그인이 아닌 선별된 카탈로그
여기에는 분명한 트레이드오프가 있다. CodexBar의 아키텍처는 프로바이더 추가를 기계적인 작업처럼 만들지만, 마찰이 전혀 없지는 않다. 프로바이더는 단순한 JSON 설정이 아니다. 새로운 열거형 항목, 디스크립터, 가져오기 전략, 앱 훅, 설정, 문서, 에셋, 레지스트리 항목이 필요하다. 작업량이 적지 않다.
대신 프로바이더가 제각각이어도 제품은 일관성을 유지할 수 있다. 모든 특수 사례를 메뉴 UI에 밀어 넣지 않고도 Codex에는 OAuth와 CLI 폴백을, Claude에는 소스 계획을, 다른 프로바이더에는 브라우저 쿠키, API 키, 로컬 프로브, 상태 폴링, 초기화 라벨, 토큰 비용 요약을 제공할 수 있다.
이는 개인정보 보호 기조도 설명한다. CodexBar의 README는 비밀번호를 저장하는 대신 기존 세션을 재사용하고 알려진 로컬 위치를 읽는다고 말한다. 아키텍처의 형태도 이를 뒷받침한다. 프로바이더별 전략은 디스크립터 계획 뒤에 있고, 앱 쪽 식별자 필드는 명시적으로 격리된다. 나는 이것을 전면적인 보안 감사로 확대해 해석하지 않겠다. 코드에서 그 경계가 보인다고만 말하겠다.
이 도구는 어디에 자리하는가?
AI 코딩 도구의 더 넓은 지도에서 CodexBar는 코딩 에이전트 내부가 아니라 그 주변의 운영 계층에 자리한다. Aider는 모델이 어떤 코드 컨텍스트를 볼지 결정한다. CLIProxyAPI는 요청이 실패한 뒤 구독 계정을 라우팅한다. CodexBar는 그 옆에서 다른 일을 한다. 프로바이더 한도를 운영 대시보드로 바꾼다.
축은 할당량의 진실을 누가 소유하는가다.
| 도구 형태 | 소유하는 것 | 완전히 소유할 수 없는 것 |
|---|---|---|
| 코딩 에이전트 | 컨텍스트, 편집, 도구 루프 | 벤더 할당량 구간 |
| 구독 프록시 | 요청 라우팅과 쿨다운 대응 | 프로바이더가 숨긴 실제 한도 |
| CodexBar | 사용량 근거, 초기화 표시, 프로바이더 상태, 로컬/계정 소스 선택 | 프로바이더의 비공개 할당량 원장 |
마지막 열이 중요하다. CodexBar는 프로바이더가 신호를 노출할 때만 그 신호를 정규화할 수 있다. 폴링하거나, 스크레이핑하거나, 로컬 파일을 읽거나, CLI에 물어보거나, OAuth를 사용하거나, 오래된 상태나 오류 상태를 표시할 수는 있다. 모든 벤더를 투명하게 만들 수는 없다.
그래서 솔직하게 읽으면 이렇다. CodexBar는 프로바이더의 복잡성을 명시적으로 드러내는 방식으로 확장한다. 프로바이더의 난잡함을 없애지 않는다. 그 안에 가둔다.
언제 선택하면 좋을까?
여러 AI 코딩 도구에 비용을 내고, 보이지 않는 초기화 구간에 하루의 흐름이 좌우된다면 CodexBar가 실용적으로 잘 맞는다. 소스에는 바로 그 난잡함을 위해 만든 아키텍처가 보인다. 선별된 프로바이더 ID, 디스크립터가 소유하는 계약, 전략 파이프라인, 앱과 CLI가 공유하는 fetch outcome이다.
설정만으로 아무 프로바이더나 추가할 수 있는 개방형 플러그인 런타임을 원한다면 이 도구는 맞지 않는다. 컴파일 타임 카탈로그 자체가 핵심이다. CodexBar는 임의 확장성보다 제품 일관성을 선택했다. 쿠키, OAuth 자격 증명, 로컬 로그, CLI, 결제 화면을 다루는 데스크톱 앱이라면 아마 올바른 선택일 것이다.
내가 붙일 표현은 이렇다. 메뉴 막대의 얼굴을 한 프로바이더 사용량 측정 런타임.
방법론과 범위
나는 커밋 a83a83f의 CodexBar v0.41.0을 읽었다. Sources/CodexBarCore/Providers, Sources/CodexBar/Providers/Shared, CLI 진입점, 앱 새로고침 경로에 초점을 맞췄다. 열 개의 주장을 고정된 소스와 대조했고, 해당 작업의 주장 원장에서 확인했다.
범위의 한계도 분명히 적어둔다.
- 프로바이더별 가져오기 모듈을 전부 감사하지는 않았다. 이 글은 각 벤더 파서의 정확성이 아니라 프로바이더 아키텍처를 다룬다.
- macOS 앱을 실행하지 않았다. 여기서 설명한 UI 동작은 실제 앱 세션이 아니라 소스 경계와 패키지 구조에서 추론했다.
- 식별자 격리에 관한 설명은 내가 읽은 명시적인 앱 구현 규칙과 프로바이더별 데이터 형태에 한정한다. 전면적인 개인정보 보호 또는 보안 리뷰가 아니다.