openCodexMicro

Turn your Ulanzi D200 into Codex Micro — plus the controls that make it a complete Codex Desktop companion.

中文说明

openCodexMicro gives Codex Desktop a dedicated hardware surface. See what your latest tasks are doing, jump between them with one press, and keep the actions you use most under your fingertips.

What it does

Feature	Behavior
Five live task keys	Merge local and Codex-managed SSH tasks in Most Recent order, with idle, thinking, complete, input/approval, or error
Instant task switching	Opens the exact task shown on the physical key
Codex controls	Fast, Pin, New, Fork, Steer, Mic, and Submit
Usage at a glance	Shows the remaining weekly allowance and refreshes it automatically
Clock and Focus	Keeps the D200 firmware clock and uses it as a Codex focus key
Renderer-native integration	Uses Codex's own Micro store for local/SSH ordering, status, selection, and routing
Responsive display	Sends only changed keys and keeps input ahead of display transfers
HID recovery	On daemon start or USB reconnect, restores cached content when available, then fully refreshes all keys

This is an unofficial project for macOS, Codex Desktop, and Ulanzi D200. The entire project was vibe-coded with Codex.

Install

Requirements:

• macOS with Codex Desktop installed
• Ulanzi D200 connected over USB
• Node.js 20+
• Python 3.11+ with venv

Clone the repository, then run:

npm install
npm run setup

The installer creates an isolated Python environment, installs hidapi and Pillow, registers the D200 and bridge sidecar LaunchAgents, and installs Codex Bridge.app in ~/Applications. Existing CodexKeyboard installations are migrated automatically; a legacy custom theme is copied before the old runtime is removed.

For fast direct switching, quit Codex and double-click Codex Bridge.app. It starts the real Codex executable with a loopback-only CDP endpoint. Task keys then use Codex's own Micro event bus, including its saved SSH host/project routing. The official Micro page reports the emulated device as connected. Steer invokes Codex's real composer action instead of synthesizing an Enter shortcut. Fast, Fork, Submit, and Mic use Codex Micro events; Pin and New invoke the matching renderer controls. When Bridge mode is active these actions never replay through AppleScript after an uncertain HTTP response.

The Bridge refreshes its cached renderer snapshot every 500ms. Expensive asset discovery and React Fiber traversal run only once per renderer lifecycle; subsequent snapshots read cached Micro store references. This also preserves temporary client-new-thread:<uuid> tasks until Codex promotes them to formal thread UUIDs.

If Codex was launched normally, openCodexMicro automatically starts a local-only app-server/rollout fallback and shows only local tasks. It does not open SSH sessions or read remote SQLite by default. --native-state retains the older local/SSH monitor as an explicit diagnostic mode.

When Bridge mode is unavailable, Mic falls back to the configured realtimeVoice.toggleMicrophoneMute shortcut. The installer adds Command+Alt+M only when that command has no binding; an existing user override is preserved. Steer deliberately has no shortcut fallback because Enter variants can submit or queue instead of steering.

See Setup and operations for permissions, logs, diagnostics, updates, migration, and uninstall instructions.

Configure

openCodexMicro follows Codex Desktop's own shortcuts instead of maintaining a second shortcut system.

Shortcut overrides:

~/.codex/keybindings.json

Submit behavior:

~/.codex/config.toml

Theme overrides:

~/Library/Application Support/openCodexMicro/icon-theme.json

Shortcut and Desktop settings are read when a key is pressed, so they normally do not require a driver restart. Theme changes require a display refresh.

See Configuration for supported commands, shortcut syntax, Submit/Steer behavior, physical key remapping, and theme options.

See CHANGELOG.md for release notes.

The repository also includes reusable Codex skills:

Skill	Purpose
install-open-codex-micro	Install or update, confirm shortcut changes, review permissions, and choose whether to start the daemon
customize-open-codex-micro-icons	Replace or generate task and action icons
remap-open-codex-micro-keys	Move existing controls or implement a new key action

Documentation

• Configuration
• Setup and operations
• Architecture
• D200 protocol notes
• Engineering constraints

License

Released under the MIT License. See THIRD_PARTY_NOTICES.md for third-party attributions.