BusyBar Codex

Turn a BUSY Bar into a tactile, two-screen controller for the Codex macOS app.

BusyBar Codex mirrors the six native Codex Micro agent slots and their live state, lets the BUSY dial switch tasks and adjust reasoning, forwards native action keys, and turns the top-center button into Codex push-to-talk. It is an independent, open-source project—not an OpenAI or Busy Devices product.

What works

• Six live Codex task slots with native white/blue/green/amber/red status semantics
• Task activation and native double-tap behavior
• Press-and-hold and double-tap dictation gestures using the Mac microphone
• Reasoning-effort adjustment with the BUSY dial
• All six action slots from your current Codex Micro layout—not a hard-coded approximation
• Codex Micro analog navigation and dial click
• Front 72×16 task/status view and rear 160×80 labeled control dashboard
• Local Wi-Fi BUSY API with protobuf button/encoder events
• Safe interactive hardware demo that never sends a Codex command

The control surface maps the smaller BUSY input set into four visible layers:

Layer	Dial	Select / OK	Back	Top-center / Start
Tasks	Browse six tasks	Activate task and open its action palette	Exit Codex	Hold to talk; double-tap for hands-free
Actions	Highlight six live Micro action icons	Run highlighted action	Tasks; hold for Navigation	Dictation
Navigation	Choose up/right/down/left	Send joystick direction	Actions	Dictation
Reasoning	Increase/decrease effort	Native Micro dial click	Tasks	Dictation

Select a task to open its icon-based action palette. Hold Select / OK from any non-reasoning layer to enter Reasoning, or hold Back from Actions for Micro navigation. Back returns through the hierarchy; pressing it from the task list clears the BUSY display and exits the controller. Move the BUSY Bar switch to APPS to enable control; other switch positions pause it.

The Actions layer follows whatever is configured in Codex Settings → Codex Micro, including defaults such as Fast, Approve, Decline, Fork, Dictation, and Send. The rear screen tells you exactly what the BUSY controls do in every layer.

Requirements

• macOS with the Codex desktop app installed
• BUSY Bar with the local Wi-Fi HTTP API enabled
• Node.js 20 or newer
• Mac and BUSY Bar on a reachable local network

Install

git clone https://github.com/kylewhirl/busybar-codex.git
cd busybar-codex
npm install
cp .env.example .env.local

Edit .env.local:

BUSY_BAR_ADDR=http://10.0.4.20
BUSY_HTTP_PASSWORD=your-local-http-password

Check the setup without changing anything:

npm run doctor

For the first real launch, quit Codex and run:

npm run build
npm start

BusyBar Codex launches the signed app through macOS LaunchServices with a random Chrome DevTools port bound only to 127.0.0.1. If Codex is already open, it will refuse to disrupt your work. You can explicitly permit a graceful restart:

npm start -- --restart-codex

Hardware-only demo

The demo renders realistic tasks and exercises every BUSY input without controlling Codex:

npm run demo

Press Ctrl-C to clear the demo display.

Official emulator

BUSY Bar Emulator can exercise the controller without touching Codex or requiring hardware. Start the emulator on its default address, then run:

BUSY_BAR_ADDR=http://127.0.0.1:8080 \
BUSY_HTTP_PASSWORD=emulator \
npm run demo

Use the emulator's Scenarios tab to send dial, button, and switch events. The controller detects the emulator and uses its SSE input bridge automatically; real BUSY Bars continue to use the firmware's protobuf WebSocket stream.

For the repeatable end-to-end test:

npm run test:emulator

This verifies task selection and activation, the icon action palette, Back navigation and exit, dictation press/release, switch pause/resume, and both display payloads. The emulator currently renders the 72×16 front matrix and stores—but does not visually render—custom elements for the 160×80 rear OLED.

How it works

flowchart LR
  B["BUSY Bar buttons, dial, and displays"] <-->|"local HTTP + protobuf WebSocket"| C["BusyBar Codex controller"]
  C <-->|"loopback-only Chrome DevTools Protocol"| D["Codex desktop renderer"]
  D --> S["Native Micro task and action stores"]

Loading

The official Codex Micro documentation describes the native six-agent display, action keys, microphone, navigation, and reasoning dial. Codex also has a documented, open-source App Server protocol, but App Server creates standalone clients; it does not currently provide the desktop UI switching, native dictation, or Codex Micro action surface needed here. This project therefore uses a local renderer bridge for those interactions.

That bridge relies on undocumented Codex desktop internals and may need updates when the app changes. Compatibility-sensitive code is isolated under src/codex/, covered by tests, and derived from the research in codex-stream-deck and codex-micro-stream-deck-emulator. See THIRD_PARTY_NOTICES.md.

Native virtual-HID track

The cleanest future transport is a signed virtual Codex Micro HID device, which would let Codex launch normally without a shim or debugging flag. macOS restricts that capability behind the Apple-issued com.apple.developer.hid.virtual.device entitlement; it cannot be enabled by source code or ad-hoc signing. This repo includes an entitlement request guide and signing template so the native track can proceed as soon as Apple approves it. The renderer transport remains the working v0.1 path.

Development

npm test
npm run check
npm run build

The test suite covers BUSY protobuf and emulator-SSE input decoding, all controller layers, native event mappings, status normalization, both display payloads, local launch security, and renderer target selection.

Privacy and security

• The Codex debugging endpoint is always bound to 127.0.0.1.
• No external relay or inbound network server is created.
• Conversation and prompt bodies are not read or logged.
• BUSY credentials stay in ignored environment files.
• A running Codex session is never restarted unless --restart-codex is explicitly supplied.

See SECURITY.md for the trust boundary.

License

MIT. See LICENSE and THIRD_PARTY_NOTICES.md.