Codex ATOM

What it is

Codex ATOM turns an existing PreSonus ATOM MIDI controller into a tactile control surface for Codex Desktop on macOS.

The starting question was simple: could hardware I already owned replace the useful parts of a dedicated Codex controller? The result is a working Swift bridge with task switching, prompt submission, scrolling, reasoning controls, workflow shortcuts, and per-pad RGB task state.

What it does

• Pads map to pinned Codex tasks. A single press switches to corresponding task
• Pad colors show idle, thinking, running, needs-input, unread-complete. Completed tasks remain green until viewed.
• Navigation Left and Right select the transcript or sidebar as Knob 2's scroll target.
• Knob 3 adjusts reasoning effort through verified Codex commands.
• Play submits the current prompt, Song Setup creates a task, and Record provides a stable press-only dictation toggle.
• A menu bar app provides pause/resume, activation modes, diagnostics, DAW guarding

How it works

The hardware path is:

PreSonus ATOM → CoreMIDI → normalized controller event → ATOMActionMapper → capability-checked Codex dispatcher.

The state path is:

Codex Desktop local metadata → TaskStateReducer → TaskVisualState → ATOM Native Control RGB output.

Codex ATOM reads task identifiers and runtime metadata locally. It does not decode or persist prompts, responses, command output, diffs, or paths. Unsupported actions fail closed instead of falling back to ambiguous UI automation.

The RGB transport includes Native Control initialization, blink and breathe modes, reconnect recovery, diff-only updates, and restoration to normal MIDI mode on shutdown.

Built with Codex and GPT-5.6

Codex was the primary development environment for the project. The work began in one long-running Codex task, where GPT-5.6 helped turn the initial feasibility question into a two-phase spec: reliable controller input first, then task-state RGB and product completion.

Codex and GPT-5.6 helped inspect Codex Desktop behavior, design the architecture, implement the Swift 6 CoreMIDI bridge, research and validate the ATOM Native Control protocol, add the local task-state integration, build Judge Mode, and write 115 automated tests.

My part of the loop was physical verification. I tested the pads, buttons, encoders, focus behavior, scrolling, task switching, dictation, and RGB on the real ATOM, then returned the actual layout, logs, and failures to the same task. That hardware-feedback loop exposed several assumptions that looked reasonable in code but were wrong in use.

The main product decisions stayed explicit: background task switching must not steal focus; completed tasks remain green until acknowledged; scrolling needs a deliberate transcript/sidebar target; and unreliable capabilities must not pretend to work.

Judge Mode

Judges do not need an ATOM or a local build. Download the packaged macOS app from the private GitHub Release, launch it, and choose Open Virtual Controller… from the ATOM menu bar item.

Fixture Mode exercises the production mapper, dispatcher, task reducer, capability checks, and RGB renderer using deterministic task data. Run Scenario demonstrates working → needs input → unread complete → error → acknowledgement → idle.

Live Mode is optional. It can control an installed Codex Desktop session through the same production capability path.

Honest boundaries

The Codex task-state integration uses a private, versioned local Desktop protocol. Protocol mismatches degrade safely while leaving the MIDI input controller usable.

True push-to-talk, semantic interrupt, and safe approval/decline do not have stable supported interfaces in the tested Codex build. Those actions remain explicitly unavailable rather than using unsafe fallbacks.

Hardware-only verification still covers CoreMIDI input, ATOM Native RGB transport, physical latency and reconnect behavior, encoder detents, and physical buttons. The repository includes the exact parity checklist and soak-test procedure.

Built With

• appkit
• codex
• coremidi
• gpt-5.6
• macos
• swift-6