feat(macos): bring CodexBar-style usage visibility to OpenCodex

[JayYun98]

Summary

A CodexBar-inspired menu bar for the traffic OpenCodex routes.

I use both OpenCodex and CodexBar. CodexBar made checking usage from the menu bar a habit. Once I started routing more of my work through OpenCodex, I wanted that same quick glance at OpenCodex’s own requests, tokens, and account limits.

This adds an optional native macOS companion and settings integrated into the existing Usage page. Click the menu-bar counter to see today’s usage, a token-history chart, and remaining account limits. Open the dashboard when you want to change what appears. Quitting the companion leaves the proxy running.

• See where the tokens went. Line or stacked-bar charts, grouped by model or model + recorded account. Choose the interval and total, per-request average, or per-request maximum.
• Keep the limits together. Codex session and weekly remaining bars; OpenCode Go session, weekly, and monthly bars where available. Unknown or expired observations stay unknown.
• Make the display yours. Provider visibility, colours, chart dimensions, and literal text templates share one monitor config. Menu bar settings follow Coverage breakdown within Usage. The preview and display settings sit together; provider controls have their own tab inside that section.

CodexBar is the inspiration for the menu-bar workflow, not a dependency or an official integration. No CodexBar source is copied. The native companion uses AppKit, SwiftUI, and Swift Charts without third-party Swift dependencies.

Screenshots

Updated Usage integration, after Coverage breakdown. Captured from the current local GUI using read-only usage snapshots; personal identifiers were replaced before rendering.

Earlier prototype views:

Local macOS prototype, running alongside OpenCodex 2.46.0. The PR changes have separately been ported to dev. Email and the personal account label are redacted before capture; usage values are unchanged.

Scope of this draft

The companion currently requires macOS 14+, a local proxy on port 10100, and a loopback bridge on port 10101. Build it with sh native/menubar/build.sh; there is no installer or login item. The native menu supports English and Korean, with a system-language default and a menu language selector. Built-in summary templates follow that choice; custom templates are preserved. The dashboard uses its existing locale catalogs, with English fallbacks for some new strings.

The monitor reads existing usage history and cached Codex quotas. OpenCode Go uses a fixed read-only usage endpoint. It does not change routing, select accounts, or initiate login. The loopback bridge exposes display data and monitor configuration, never provider keys or account tokens; writes are origin-checked and revision-checked. Account email remains private display data in local snapshots, which is why it is redacted in these screenshots. This does not isolate mutually untrusted processes running as the same OS user.

I would welcome maintainer feedback on keeping the companion in-tree and the local bridge boundary before broadening platform, port, or packaging support.

Verification

The branch is based on dev at f117c20d1244bf20d8cf5bd35de5bb7c71003799. Typecheck, GUI tests, lint, and build were rerun after updating the base. Earlier checks below were run on 3d5efc72554505c581b3af2a68d108e9221f14b7; native language checks were run after adding English support.

• bun run typecheck and the CI-specific TypeScript checks pass.
• cd gui && bun test --isolate tests — 2,189 tests pass on the updated base, including the template-row regression check.
• cd gui && bun run lint and bun run build pass.
• React Doctor 0.9.11, changed scope against origin/dev — no issues found.
• cd docs-site && bun install --frozen-lockfile && bun run build passes (465 pages).
• bun run structure:check, bun run privacy:scan, bun run skill:surface:check, and git diff --check pass.
• cd native/menubar && sh build.sh — native build and data/config/HTTP self-checks pass, including language selection, English fallback, legacy default migration, and custom-template preservation.
• OpenCodexMonitor --probe — read-only check against the existing local proxy passes.

The earlier full backend run on 3d5efc72554505c581b3af2a68d108e9221f14b7 completed with 27,021 passing tests, 5 failures, and 57 skipped tests, including the runner’s serial lanes. Those five failures were also reproduced in an untouched worktree of that same upstream commit: the Windows spill-queue timeout, preferred-runtime fallback probe, missing-version runtime selection, and two Linux sandbox executable checks on this Mac. The full backend suite has not been rerun after the final base update, so these are historical results, not an assertion about the new base. The local-CI readiness box stays unchecked; upstream CI and Codex/CodeRabbit review are still pending.

The local prototype was also checked in the browser: tab navigation, configuration saves, graph regrouping, and collapsed JSON settings. The PR worktree has not replaced the running proxy or installed companion.

Checklist

• Scope stays focused and avoids unrelated cleanup.
• Docs or release notes were updated when needed.
• Security-sensitive changes were reviewed for secrets, auth, and unsafe defaults. An independent local review was performed; maintainer security review remains pending.

• All CI tests are green on my local testing.

• I pushed my PR to the latest dev commit.

• I resolved all correct Codex and CodeRabbit findings.

• My PR is ready for review.

Summary by CodeRabbit

• New Features

  • Added a local monitor page to the web dashboard with usage graphs, provider quotas, account details, model filtering, and configurable display settings.
  • Added a native macOS menu-bar monitor with charts, usage summaries, quota information, localization, and a companion dashboard.
  • Added monitor configuration editing, validation, saving, and stale-change handling.
  • Added English, German, French, Japanese, Korean, Russian, Turkish, Vietnamese, and Chinese localization entries.

• Documentation

  • Added setup, configuration, usage, and build documentation for the monitor.

• Tests

  • Added coverage for monitor navigation, routing, formatting, chart calculations, configuration, and data handling.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

⚠️ Deterministic hygiene checks failed.

• empty_catch — An empty catch block was added. Handle, report, or deliberately propagate the error. Paths: native/menubar/SelfTest.swift, native/menubar/main.swift.

[github-actions]

⏳ DRAFT

• review readiness checklist open (1/4 boxes ticked).

What to do

• Tick all four boxes in the PR description once you're done (currently 1/4).

Review readiness checklist

• ⬜ All CI tests are green on my local testing.
• ✅ I pushed my PR to the latest dev commit.
• ⬜ I resolved all correct Codex and CodeRabbit findings.
• ⬜ My PR is ready for review.

1/4 boxes ticked.

This PR stays in draft until every box above is ticked.

Hygiene

✅ Deterministic PR hygiene checks passed.

[lidge-jun]

사용량 쪽에 통합으로 설계부탁드립니다 아니면 제가 넣어보겠습니다

[JayYun98]

@coderabbitai review

[coderabbitai]

⚠️ Action not completed

Pull request base or head changed.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[JayYun98]

일단 이런식으로 나오고, 덕분에 잘쓰고 있습니다! ㅎㅎ.
대시보드에서 보내는건 수정하고 커밋해두겠습니다 :) 입맛에 맞게 수정하시고 머지해도 괜찮습니다!

[lidge-jun]

GOAT

[lidge-jun]

리뷰 · 우선순위 72 / 80

이 PR은 맥 메뉴 막대에 OpenCodex 오늘 사용량을 붙입니다. 요청 수, 토큰 그래프, Codex 잔여량, OpenCode Go 잔여량을 보여 줍니다. 모니터만 끄면 프록시는 그대로 돕니다. 설정 칸은 사용량 페이지에서 Coverage 다음에 있습니다. 유지자가 말한 사용량 통합입니다. 그 칸은 최신 커밋 478a73b6에 들어 있습니다.

base는 dev입니다. types.ts / config.ts 분리와는 겹치지 않습니다. 아직 draft이고, 준비 체크는 1/4입니다. 작성자는 네이티브 자체 검사와 GUI 테스트를 돌렸다고 적었습니다. 백엔드 전체 테스트는 마지막 base 갱신 뒤에 다시 돌리지 않았습니다.

모니터는 127.0.0.1:10101만 엽니다. 출발 주소가 대시보드(http://127.0.0.1:10100 또는 http://localhost:10100)가 아니면 거절합니다. 설정을 저장하려면, 아까 읽은 설정과 같은 번호여야 합니다. 관리 토큰과 프로바이더 키는 이 포트로 나가지 않습니다. 관리 토큰을 10100에 보내기 전에는, 그 포트를 연 프로그램이 지금 사용자 것인지 확인합니다. 다른 주소로 넘어가는 응답에는 토큰을 따라가지 않습니다.

라인 native/menubar/main.swift refreshProviders 183행 - 60초마다 ~/.opencodex/config.json에서 OpenCode Go 키를 읽어 https://opencode.ai/zen/go/v1/usage로 보냅니다. keychain:, env:, ${로 시작하는 값은 건너뜁니다. 파일에 그대로 적힌 키는 나갑니다. 메뉴 막대 프로세스가 그 키를 들고 밖으로 호출합니다. 10101 포트가 키를 숨기는 것과는 다른 일입니다.

라인 gui/src/i18n/de.ts 9행 monitor.averageNote - ja.ts, ru.ts, tr.ts, zh.ts도 새 문구 대부분이 영어입니다. vi.ts는 제목 하나만 그 언어입니다. fr.ts, ko.ts, zh-TW.ts는 번역되어 있습니다. 작성자도 영어가 남는다고 적었습니다. 그 언어 화면에는 영어가 섞입니다.

라인 native/menubar/main.swift loadConfig 216행 - 실패 문구가 config.json입니다. 모니터 설정 파일은 ~/.config/opencodex-monitor/config.json입니다. 계정과 키는 ~/.opencodex/config.json입니다. 읽기에 실패하면 어느 파일을 고칠지 헷갈립니다.

메인테이너의 판단이 필요한 지점

• 이 동반 앱을 저장소 안에 둘지. 설치 파일과 로그인 항목은 없고, sh native/menubar/build.sh로만 만듭니다. 맥 14 이상입니다. 이 빌드는 CI에 없습니다.
• OpenCode Go 키를 메뉴 막대가 매분 밖으로 보내는 것을 허용할지
• 포트 10100과 10101을 고정으로 둘지. 작성자도 포트를 넓히기 전에 경계를 물어봤습니다.
• 원격 허브에 붙은 사용량 화면에서는 이 칸이 빠집니다. gui/src/pages/Usage.tsx의 localMonitor={!connected}입니다. 로컬 단독 화면에서만 보입니다.
• de, ja, ru, tr, vi, zh 번역을 머지 전에 채울지
• 스크린샷 세 장(docs/pr-assets/macos-menu-bar-monitor/)을 dev에 남길지
• 같은 맥 사용자라면 출발 주소만 맞추면 계정 이메일을 읽고 모니터 설정을 바꿀 수 있습니다. 작성자가 이미 적었습니다. 키는 그 포트로 안 나갑니다.

너의 추천
draft로 두세요. 키를 밖으로 보내는 줄을 허용할지 먼저 정하세요. 허용하면 빈 번역을 채우고, 체크리스트를 닫은 뒤에 머지하면 됩니다. 사용량 페이지에 붙인 칸은 이미 있습니다. 봇은 머지하지 않습니다.

이 댓글은 grok-bot이 작성했습니다

[lidge-jun]

추가 리뷰 · 우선순위 72 / 80

지난 리뷰의 맨 위 커밋은 478a73b6이었습니다. 지금은 6fabe14입니다. 모니터를 만드는 파일은 내용이 같습니다. native/menubar/main.swift, SelfTest.swift, WebBridge.swift, MonitorData.swift, 사용량 페이지, 번역 파일이 그렇습니다.

옮긴 일은 아래쪽 dev를 새로 받은 것입니다. 예전 바닥은 f117c20(#5153)이었습니다. 그 위에 네 커밋을 다시 얹었습니다. #5155 구조 계약, #5152 Devin 전송 한도, #5105 봇 멘션 막기, #5106 doctor의 CODEX_HOME 경로입니다. 메뉴 막대가 하는 일은 안 바뀌었습니다.

그 다음에 dev가 또 앞으로 갔습니다. 이 브랜치에 없는 dev 커밋이 15개입니다. 그중 #5157은 사용량 장부를 프로세스 하나만 쓰게 잠급니다. 이 PR 파일 목록에는 그 커밋이 손댄 파일이 없습니다. 지금 GitHub는 합칠 때 충돌이 없다고 표시합니다. 설명의 "최신 dev에 올렸다" 칸은 지금 기준으로는 틀립니다.

라인 native/menubar/main.swift refreshProviders 178행 - OpenCode Go 키를 60초마다 https://opencode.ai/zen/go/v1/usage로 보냅니다. 타이머는 100행입니다. 이 줄은 그대로입니다.

라인 native/menubar/main.swift loadConfig 216행 - 읽기 실패 문구가 여전히 config.json입니다. 모니터 설정은 ~/.config/opencodex-monitor/config.json이고, 계정과 키는 ~/.opencodex/config.json입니다.

라인 gui/src/i18n/de.ts monitor.averageNote - de, ja, ru, tr, vi, zh는 영어가 남아 있습니다. 번역 파일도 안 고쳤습니다.

메인테이너의 판단이 필요한 지점

• 키를 밖으로 보낼지, 동반 앱을 저장소에 둘지, 포트 10100과 10101을 고정할지, 원격 허브 화면에서 이 칸을 뺄지, 빈 번역을 채울지, 스크린샷을 남길지. 지난 리뷰와 같은 질문입니다.
• 최신 dev에 다시 올릴지는 작성자가 정하면 됩니다. 지금 충돌 표시는 없습니다.

너의 추천
draft로 두세요. 키를 밖으로 보내는 줄을 허용할지 먼저 정하세요. 이번 푸시는 그 줄을 고치지 않았습니다. 봇은 머지하지 않습니다.

이 댓글은 grok-bot이 작성했습니다

[devin-ai-integration]

Thank you for this, @JayYun98 — the CodexBar-style monitor work is being carried forward in #5196, which integrates it with the maintainer companion on feat/macos-app (rebased onto current dev) and adds a widget. The monitor settings stay inside the Usage page as one section, per the earlier request.

Closing this PR as superseded by #5196. Since the head of this PR lives on your fork and cannot be pushed to by maintainers, if you'd like to keep contributing to this feature please push follow-up commits to feat/macos-app on lidge-jun/opencodex (or open a PR against it) — your authorship is preserved where commits are carried over, and review feedback on #5196 is very welcome.