Control Codex Desktop from an Ulanzi D200 Series through Ulanzi Studio.
OpenCodexMicro exposes Codex's live Micro state through a loopback Bridge and turns it into a native Ulanzi Studio plugin. It shows recent tasks, switches to the exact task displayed on a key, and provides Fast, Usage, Pin, New, Fork, Steer, Mic, Submit, and Latest Task & Scroll Encoder actions.
| Feature | Behavior |
|---|---|
| Five live task actions | Show Codex's Most Recent tasks with idle, working, complete, attention, or error state |
| Exact task switching | Route the selected thread through Codex's own Micro event bus |
| Codex controls | Fast, Usage, Pin, New, Fork, Steer, Mic, and Submit |
| Encoder navigation | Press to open task 1; turn left/right to scroll up/down through Ulanzi Studio's hotkey protocol |
| Live usage | Draw the remaining Codex allowance directly on the key; press to return to Codex |
| Ulanzi Studio integration | Let Ulanzi Studio own the device and manage the key layout |
| Local-only transport | Bind CDP and the Bridge API to loopback addresses only |
This Ulanzi-maintained project is an unofficial integration with Codex Desktop for macOS, Ulanzi Studio, and Ulanzi D200 Series. It is not affiliated with or endorsed by OpenAI. The entire project was vibe-coded with Codex.
Ulanzi's implementation and maintenance scope is limited to
integration/com.ulanzi.codexmicro.ulanziPlugin/. The plugin only consumes
state and action interfaces exposed through the existing local Bridge; Ulanzi
did not participate in the design, specification, development, or maintenance
of CDP or Codex's CDP implementation. See NOTICE.md for the full
responsibility boundary.
- macOS 13 or later;
- Codex Desktop;
- Ulanzi Studio 3.0.1 or later;
- Ulanzi D200 Series connected to Ulanzi Studio;
- Node.js 20 or newer only for repository-based manual installation.
An LLM or coding agent must follow these steps:
- Read AGENTS.md and inspect the installed Ulanzi Studio plugin
manifests under
~/Library/Application Support/Ulanzi/UlanziDeck/Plugins/. - Treat Codex Micro as installed only when manifest UUID
com.ulanzi.ulanzistudio.codexmicrois present and itsCodePathexists. - If it is missing or invalid, load
$install-ulanzi-studio-plugin, install the plugin, and verify its manifest and entry point. - After the plugin is verified, load
$setup-codex-bridge, install or repairCodex Bridge.appand its sidecar, and verify the local health endpoint. - Report plugin installation and Bridge connectivity separately. Do not reinstall a valid plugin unless an update or repair was requested.
After installing the Codex Micro plugin, drag any Codex Micro action onto a key and select it. Its shared Codex Bridge Setup page can:
- show whether
Codex Bridge.app, the Bridge service, and CDP are available; - install or repair the bundled Bridge without a repository or npm directory;
- launch
~/Applications/Codex Bridge.app; and - recheck the connection or open the full installation guide.
The installer writes only to the current user's Applications, Application
Support, and LaunchAgents directories and does not require sudo.
git clone https://github.com/UlanziTechnology/OpenCodexMicro.git
cd OpenCodexMicro
npm install
npm run install:plugin
npm run setupQuit Ulanzi Studio before running npm run install:plugin. The command
validates and atomically installs the prebuilt plugin. npm run setup builds
the loopback Bridge sidecar, registers its user LaunchAgent, and installs
Codex Bridge.app in ~/Applications.
Reopen Ulanzi Studio. Quit Codex Desktop, then open
~/Applications/Codex Bridge.app; the wrapper starts Codex with a
loopback-only CDP endpoint. Confirm the connection with:
curl http://127.0.0.1:17373/health
curl http://127.0.0.1:17373/stateIn Ulanzi Studio, drag the Codex Micro actions onto the desired keys. See Setup and operations for installed paths, diagnostics, updates, and uninstall instructions.
Important: When using Codex Micro, always launch Codex through
~/Applications/Codex Bridge.app. Do not open Codex Desktop directly.Launch command:
open ~/Applications/Codex\ Bridge.app
The physical layout is managed in Ulanzi Studio. The plugin ships these actions: Codex Task 1–5, Fast, Usage, Pin, New, Fork, Steer, Mic, Submit, and Latest Task & Scroll for Encoder controls. No separate device daemon or shortcut mapping is required.
Select any configured action to open the shared Codex Bridge Setup page. It shows Bridge installation, service, and CDP status and provides Install / Repair and Launch controls.
On macOS, enable Ulanzi Studio in System Settings > Privacy & Security > Accessibility so Encoder rotation can send mouse-wheel events.
See Configuration for action behavior and layout guidance.
The repository includes two reusable Codex skills:
| Skill | Purpose |
|---|---|
setup-codex-bridge |
Install, update, verify, or repair Codex Bridge.app and its sidecar |
install-ulanzi-studio-plugin |
Install the repository's prebuilt plugin directory into Ulanzi Studio |
Project-authored code is released under the MIT License. See the modification and responsibility notice for upstream attribution, material changes, Ulanzi maintainership, independence from OpenAI, and responsibility boundaries. Bundled and build-time dependencies are documented in third-party notices.