An open-source macOS helper that puts Codex usage, session context, model controls, and explicit approval actions on a physical MacBook Pro Touch Bar.
Important
This is an independent community project. It is not an official OpenAI product and is not affiliated with or endorsed by OpenAI or Apple.
Codex Status Touch Bar running on a physical MacBook Pro Touch Bar.
- 5H and 7D quota — remaining percentage and reset time. Tap either value to request an immediate refresh.
- Selected-thread context — the selected thread title plus current tokens compared with its model context window.
- Model and effort — view the active CLI or Desktop session, then use a centered full-bar Model/Effort control when the local Codex Desktop bridge is available.
- Three-button approvals — approve, reject, or request changes for explicitly registered decision gates.
- Desktop widgets — Small and Medium WidgetKit views with a rolling 24-hour token chart.
- Self-healing presentation — restores the app-owned Touch Bar after app switches and wake events without restarting macOS Touch Bar services.
| Requirement | Details |
|---|---|
| macOS | 15 or later |
| Hardware | A MacBook Pro with a physical Touch Bar |
| Codex data | Codex CLI installed in ~/.local/bin, /opt/homebrew/bin, or /usr/local/bin |
| Interactive changes | Codex Desktop with bundle ID com.openai.codex is optional for display, but required for model changes and approval delivery |
| Selected thread | Accessibility permission for Codex Status Touch Bar; read-only and used only to identify the selected local Codex route |
| Building | Full Xcode with Swift 6 and the macOS 15 SDK or later |
The desktop widget can render on a compatible Mac without a Touch Bar, but Touch Bar controls require physical Touch Bar hardware.
This first public release is source-distributed. Clone and build it locally:
git clone https://github.com/binlabongbom/codex-status-touch-bar.git
cd codex-status-touch-bar
xcode-select -p
bash scripts/build-app.sh
bash scripts/verify-app.sh
sudo ditto -x -k 'dist/Codex Status Touch Bar.zip' /Applications
open '/Applications/Codex Status Touch Bar.app'If xcode-select -p does not point to a full Xcode installation, select one first:
sudo xcode-select --switch /Applications/Xcode.app/Contents/DeveloperThe local build is ad-hoc signed and not notarized. macOS may require you to Control-click the app, choose Open, and confirm once. Do not disable Gatekeeper globally.
To install and register the desktop widget:
bash scripts/install-local-widget.shThen open the macOS Widget Gallery and add Codex Status in Small or Medium size.
For detailed steps, see Installation and Usage.
The Medium Codex Status widget running on the macOS desktop.
The included WidgetKit extension provides a glanceable view of Codex activity even when the Touch Bar is collapsed:
- Rolling 24-hour chart — 48 columns represent consecutive half-hour slots across the exact preceding 24 hours.
- Usage by model — each column stacks locally aggregated token totals. Sol is purple, Terra is blue, Luna is green, and unrecognized models use the system secondary color.
- Local time guides —
00,06,12, and18markers move through the chart as the rolling window advances. - Quota footer —
5Hand7Dshow the remaining quota, colored progress, reset time, and stale/unavailable state. - Small and Medium sizes — both are available from the macOS Widget Gallery; the Medium size provides the clearest chart detail.
The background helper must be running to publish new snapshots. Widget data is stored locally as aggregate half-hour totals; prompts and responses are never copied into it. If a fresh history read fails, the last eligible snapshot can remain visible for up to 15 minutes and is marked stale rather than replaced with invented data.
Install or refresh the local widget extension with:
bash scripts/install-local-widget.shAfter rebuilding an ad-hoc-signed version, macOS may remove the previous widget placement because the code identity changed. Open Widget Gallery and add Codex Status again if it disappears.
The helper refreshes every 30 seconds while active. Tapping 5H, 7D, or the Codex Control Strip icon requests a new read immediately. Existing values stay visible during refresh and remain visible if the request fails. After sleep, the helper cancels any inherited request, re-presents the Touch Bar, and performs a fresh read.
Codex can expose only one quota window for some account plans. In that case the available window remains visible and the window not included in the plan displays N/A. A -- value means the helper could not obtain a current or eligible cached value.
Tap MODEL:EFFORT once to replace the status bar with one centered control surface. Choose SOL, TERRA, or LUNA on the left, use the discrete EFFORT slider on the right, and use the Codex mark in the middle as the visual divider. The selected complete pair is applied only to the detected active thread.
The helper starts its 30-second data refresh at launch even when Codex Desktop is not running. In this CLI display mode, quota comes from codex app-server; session, model, effort, and Widget history come from bounded local session logs. Interactive model changes and approval responses remain fail-closed unless Codex Desktop confirms the exact thread.
While Codex Desktop is frontmost, the helper checks the selected thread once per second through macOS Accessibility. The context block uses that thread's title instead of SESSION and refreshes immediately when selection changes. After switching to another app, it keeps the last confirmed thread pinned and continues reading its local rollout in the background. The permission is read-only; the helper never controls the keyboard or pointer.
The app does not parse ordinary chat text or guess whether a sentence is an approval request. An agent or automation must register a genuine decision gate explicitly:
'/Applications/Codex Status Touch Bar.app/Contents/MacOS/CodexTouchBar' \
approval-request \
--thread-id 019f56ad-6af2-7163-8771-cf8c5169e9d0 \
--question 'Approve this design and continue?'The Touch Bar then shows three actions: Approve, Reject, and Request changes. A success state appears only after Codex Desktop confirms delivery to the exact source thread. See Approval integration.
All processing stays on the Mac. The helper:
- reads rate-limit data from the local
codex app-serverand bounded tails of local Codex session logs; - publishes only aggregate usage to its local WidgetKit container;
- never copies prompts or responses into widget snapshots;
- never opens or reads Codex credential files;
- sends model selections and approval responses only to the local Codex Desktop IPC endpoint.
No usage telemetry is transmitted by this project.
- The Touch Bar presentation uses private macOS APIs. A future macOS update may break it.
- Model selection and approval delivery use a versioned local Codex Desktop IPC route. A future Codex update may require a project update.
- Without Codex Desktop, CLI-derived status and Widgets remain available, but changing an already-running CLI thread from the Touch Bar is intentionally unsupported.
- Exact selected-thread following requires macOS Accessibility permission. Without it, the helper keeps the last confirmed thread or falls back to the latest valid local session instead of guessing from background activity.
N/Ameans the account plan does not currently expose that quota window.--means no current or eligible cached value could be read.- The self-healing watchdog can re-present or relaunch this app, but intentionally does not restart system Touch Bar processes or change global Touch Bar preferences.
- Ad-hoc signatures are suitable for local source builds, not seamless public binary distribution. Stable signed releases require an Apple Developer ID and notarization.
- Widget placement may be lost after installing a differently ad-hoc-signed build; add the widget again if necessary.
Read Troubleshooting before opening an issue.
swift test
swift build -c release
bash scripts/build-app.sh
bash scripts/verify-app.shRuntime checks involving the actual Touch Bar, wake behavior, Control Strip, Widget Gallery, and Codex Desktop must be performed manually on supported hardware.
Contributions are welcome. See Contributing, Security, and the MIT License.
The public project and app display name are Codex Status Touch Bar. Internal executable names and bundle identifiers retain CodexTouchBar for upgrade compatibility.