Turn a cheap, off-the-shelf Ajazz AKP03E macro pad into a first-class OpenAI Codex controller — six LCD keys that light up with your live Codex task state, plus knobs and buttons that drive Codex actions. No vendor hardware, no browser, and it survives reboots.
The OpenAI Codex desktop app can drive a small hardware macro pad — the Codex Micro (by Work Louder). codexdeck makes a widely-available Ajazz AKP03E deck look exactly like a Codex Micro to the app, so Codex lights the keys with each task's live state and reads your button/knob presses — with zero vendor hardware.
Windows-first. A retarget of the MIT project
mpociot/codex-micro-stream-deck-emulator
(Elgato Stream Deck / macOS) to the AKP03E on Windows.
Not affiliated with OpenAI, Work Louder, or Elgato. "Codex", "Codex Micro", "Stream Deck", and "Work Louder" are trademarks of their owners. This is an independent interoperability project for people who already own the hardware.
- 🟢 Live task lighting — the six LCD keys mirror each Codex task's colour/brightness in real time.
- 🎛️ Real controls — 6 keys, 3 buttons, 3 knobs mapped to Codex actions (approve / reject / push-to-talk, reasoning depth, submit, …).
- 🖥️ Headless — a pure-Node host drives the deck over
node-hid; no browser tab, no Electron. - 🔌 Survives reboots — one-time setup, then the deck comes back on its own after every boot and Codex auto-update.
- 🔒 No test-signing — uses the Microsoft-signed usbip-win2 virtual USB host controller, so Secure Boot / HVCI stay on and untouched.
On Windows, the Codex app only recognises a Codex Micro if a real USB HID device with its
VID/PID (303A:8360) is present — a software/root device is rejected because its interface
path lacks the USB VID/PID. codexdeck supplies a genuine one: a small USB/IP server
fabricates the Codex Micro USB device and attaches it through the Microsoft-signed usbip-win2
VHCI, then bridges that virtual device to your physical AKP03E.
flowchart LR
Codex["OpenAI Codex app"]
Dev["Virtual Codex Micro<br/>(USB/IP server)"]
Emu["Codex Micro emulator"]
Deck["Ajazz AKP03E"]
Codex <-->|"USB/IP · 127.0.0.1:3240"| Dev
Dev <--> Emu
Emu -->|"lighting"| Plan["planLighting"] --> Tiles["JPEG key tiles"] -->|"node-hid"| Deck
Deck -->|"key / knob / button"| Map["input-map"] --> Emu
The whole thing runs in one Node process (apps/host): the USB/IP server, the
Codex Micro protocol emulator, the lighting planner, and the node-hid deck driver.
| Deck | Ajazz AKP03E — USB 0300:3002, 6 LCD keys, 3 buttons, 3 knobs |
| Emulated as | Codex Micro — USB 0x303A:0x8360 |
| OS | Windows 11 (Secure Boot / HVCI supported; no test-signing) |
- Prerequisites — Node ≥ 20.6, pnpm, the AKP03E plugged in, and usbip-win2 installed (its drivers are Microsoft-signed).
- Install
pnpm install --frozen-lockfile - Start the host (serves the virtual device + drives the deck)
cd apps/host && npx tsx src/host.ts - Attach the virtual device so Windows enumerates it
usbip attach -r 127.0.0.1 -b 1-1 - Open Codex — it detects the Codex Micro and the deck lights up.
To make it start at login and survive reboots, run the one-time setup in
docs/autostart.md (a per-user logon task + the usbip stash; needs admin
exactly once).
Defaults — all editable in one place
(apps/host/src/input-map.ts):
| Physical control | Codex action |
|---|---|
| 6 LCD keys | Select agent / thread slot (AG00–AG05) — also the lit keys |
| ✓ / ✗ / 🎤 buttons | Approve / Reject / Push-to-talk (hold) |
| Big knob — turn / click | Navigate composer controls / select |
| Left small knob — click | Send message |
| Right small knob — click | Fast |
apps/host headless Node host (USB/IP server + node-hid deck driver) ← the product
apps/web original browser/WebHID deck page (superseded by apps/host)
packages/emulator Codex Micro JSON-RPC protocol emulator
packages/lighting per-frame lighting → minimal deck-op planner
packages/driver AKP03E device driver (transport-abstracted)
packages/protocol AKP03E wire protocol (packets + input parsing)
packages/bridge WebSocket/socket transport bridge
scripts/ Windows autostart + usbip persistence scripts
docs/ design specs, plans, and the autostart runbook
pnpm install
pnpm -r test # ~70 unit tests across the packages
MIT. Built on and credits mpociot/codex-micro-stream-deck-emulator;
virtual USB via vadimgrn/usbip-win2. See
NOTICE for full attribution and SECURITY.md for the security model.