Codex

The Codex adapter hosts the Codex app-server protocol against a pinned CLI version. Pinning is the point: the adapter is verified against one known protocol schema, and a drift check fails the build when the installed CLI stops matching it, rather than letting a silent protocol change reach you as a broken session.

Requirements

The codex executable on the bridge machine’s PATH, authenticated with codex login or an OPENAI_API_KEY. Codex also supports in-app device-code sign-in — you can complete the login from Helmora rather than dropping into a terminal.

Codex registers as a machine agent with folder facets: one registration per machine, with per-folder rows underneath it. Choosing another folder pins a facet, it does not create a second installation.

What the adapter supports

Sessions and threads. Codex threads live in one shared per-machine store. There is no fork-on-resume model — an idle thread stays typeable from anywhere, and only a genuinely live external turn locks the composer.

Streaming tools and diffs. Tool calls and their output stream into the transcript; file edits render as diffs. Codex marks its messages as commentary (preamble, progress) or final answer, and Helmora renders both as full assistant messages — faithful to what the Codex TUI itself shows.

Approvals. Command and edit approvals surface as cards you answer from the app, and the answer feeds back into the running turn.

Questions. Codex’s ask-the-user request renders as the same choice card as every other runtime. Upstream, that request is currently restricted to plan collaboration mode; in the default mode the model answers inline instead. That’s a provider gate, not a Helmora limitation.

Plans and reviews. Plan turns render as plans. Review output renders in the transcript alongside the rest of the turn.

Models and reasoning effort. Both are switchable per session and take effect on the next turn. Collaboration mode is exposed separately from effort, because Codex treats them as separate knobs.

Permission posture. The permission-mode picker uses Codex’s own vocabulary rather than a lowest-common-denominator translation.

Usage windows. Context usage shows on the session gauge; plan usage is available from the gauge tap. Codex exposes a first-class compaction RPC, so manual compaction is a real operation with a durable receipt in the transcript.

MCP management. Configured MCP servers are listed, installable, and removable from the Tools panel, and their live status shows as a pill. Note that Codex maps every scope to its user-global configuration, so an “install for this project” acts machine-wide.

Tools catalog and diagnostics. Codex is one of the runtimes that can enumerate its tool catalog into Settings, and it reports adapter-level diagnostics into the Diagnostics tab.

External-thread mirroring. Threads you start in the codex CLI appear in Helmora, with live external turns marked as such.

Live Activities. On iOS, an active Codex turn can drive a Live Activity.

Known boundaries

• Codex has no hooks surface, so Helmora shows none.
• Sub-agent work maps to a task card in the transcript, but the sub-agent drill-in available for Claude Code is not wired for Codex yet.
• The grouped settings taxonomy is Claude-Code-specific today; Codex configuration lands in a generic section.
• Verbosity control is not exposed.

The app renders only what the active adapter declares it can do — see Architecture.