OpenCodex Usage Chip

A tiny macOS menu-bar chip that shows remaining Codex usage at a glance.

Local files only. No network. Not CodexBar, and not the OpenCodex proxy.

Why this exists

Codex already has a usage page, but you have to open the app and click into it. This chip keeps the remaining percent on the menu bar of the screen you choose.

• Green ring + 92% on the selected display
• Color: green ≥40%, orange ≥15%, red <15%
• Click for used %, reset time, credits, and data age
• Drag to reposition; pick a screen from the menu
• Refresh every 60s, or hit Refresh now
• Reads recent token_count / rate_limits snapshots from ~/.codex/sessions
• Not a floating HUD in the middle of the screen

What it is not

• Does not sign in to OpenAI / Codex / OpenCodex
• Does not read browser cookies or touch the Keychain
• Does not track Cursor, Claude, or other providers
• If you just logged in and have not run a task yet, it may show No quota data. That is expected: there is no local rate-limit snapshot yet

Install

Requires macOS 13+ and swiftc from Xcode Command Line Tools.

git clone https://github.com/yuansaysay/opencodex-usage-chip.git
cd opencodex-usage-chip
./Scripts/install.sh

The install script will:

1. Build ~/Applications/OpenCodexUsageChip.app
2. Write LaunchAgent me.opencodex.usagechip
3. Start it at login

Build only:

./Scripts/build.sh
open ./dist/OpenCodexUsageChip.app

Uninstall:

./Scripts/uninstall.sh

Or choose Quit and stop login launch from the chip menu.

If Gatekeeper blocks the first launch:

xattr -dr com.apple.quarantine ~/Applications/OpenCodexUsageChip.app

Privacy

• Reads only the tail of the newest ~80 .jsonl files under ~/.codex/sessions
• Logs go to ~/Library/Logs/opencodex-usage-chip.log and do not include session transcripts
• On launch it looks at on-screen menu-bar window positions so the chip can sit left of third-party extras. Nothing is uploaded. Use Reset position and drag if you prefer a fixed spot

How it compares

	OpenCodex Usage Chip	CodexBar	OpenCodex
Job	Local usage chip	Multi-provider menu-bar suite	Local Codex proxy
Data	~/.codex/sessions	OAuth / cookies / CLIs / many sources	Proxy and multi-account
Network	None	Yes	Yes

If you already use OpenCodex, this chip still only reads local Codex sessions. It does not read the proxy dashboard.

Develop

./Scripts/build.sh
open ./dist/OpenCodexUsageChip.app

All app logic lives in Sources/main.swift.

License

MIT

---

中文

菜单栏常驻显示 Codex 剩余用量。纯本地读取，不联网。不是 CodexBar，也不是 OpenCodex 本体。

• 固定在你选中的屏幕菜单栏，例如绿色圆环 + 92%
• 圆环颜色：绿 ≥40%，橙 ≥15%，红 <15%
• 点击查看已用比例、重置时间、credits、数据时间
• 可切换屏幕，拖动后会记住位置
• 每 60 秒刷新；也可点「立即刷新」
• 数据来自本机 ~/.codex/sessions 最近会话里的 token_count / rate_limits 快照
• 刚登录、还没跑过任务时，可能显示「暂无限额数据」

git clone https://github.com/yuansaysay/opencodex-usage-chip.git
cd opencodex-usage-chip
./Scripts/install.sh

卸载用 ./Scripts/uninstall.sh，或在菜单里点「退出并停止自启」。