This page documents the core communication protocol used between all user-facing interfaces and the codex-core agent: the Submission/Event queue pair, the Op and EventMsg enums that define every operation and notification, and the Codex struct's submit/next_event interface.
The protocol is defined in the codex-protocol crate codex-rs/protocol/src/protocol.rs1-4 and implemented by the Codex struct in codex-core. Every client—the TUI, the headless exec mode, the app server, and the MCP server—talks to the agent exclusively through this interface.
SandboxPolicy, AskForApproval) that appear as Op fields, see 2.4 Sandbox and Approval Policies.EventMsg into rendered history cells, see 4.1.2 ChatWidget and Conversation Display.EventMsg into JSON-RPC notifications, see 4.5.3 Event Translation and Streaming.Sources: codex-rs/protocol/src/protocol.rs1-4
Submission and OpA Submission is the envelope placed on the submission queue. It pairs a unique correlation ID with an operation and optional distributed trace context codex-rs/protocol/src/protocol.rs175-181
The trace field enables distributed tracing across async submission handoffs. When present, it carries traceparent and tracestate headers for OpenTelemetry integration codex-rs/protocol/src/protocol.rs180-181
Sources: codex-rs/protocol/src/protocol.rs175-181
Op is a non-exhaustive enum covering every action a client can request, such as starting a turn, approving a tool call, or requesting a code review codex-rs/protocol/src/protocol.rs209-510
Event and EventMsgAn Event is the envelope placed on the event queue. The id field echoes the Submission.id that triggered the event (where applicable) codex-rs/protocol/src/protocol.rs586-591
EventMsg is the tagged union of every notification the agent can emit, including streaming message deltas, tool execution status, and approval requests codex-rs/protocol/src/protocol.rs594-1115
Sources: codex-rs/protocol/src/protocol.rs586-591 codex-rs/protocol/src/protocol.rs594-1115
The protocol is implemented as a Submission Queue / Event Queue (SQ/EQ) pattern codex-rs/protocol/src/protocol.rs3-4 backed by async-channel channels. This decouples callers from the agent's internal execution model.
In codex-core, the Session struct manages these channels, using a Sender<Event> to emit updates and an InputQueue to manage incoming submissions codex-rs/core/src/session/session.rs32-53
Queue Architecture: Codex struct, channels, and background task
Sources: codex-rs/protocol/src/protocol.rs3-4 codex-rs/core/src/session/session.rs32-53 codex-rs/core/src/session/handlers.rs81-89
Codex InterfaceThe CodexThread (and the Codex interface wrapping it) is the primary handle to a live agent session.
| Method | Signature | Description |
|---|---|---|
submit | async fn submit(&self, op: Op) | Wraps op in a Submission with a generated ID and sends it to the session codex-rs/core/src/codex_thread.rs182-190 |
submit_with_id | async fn submit_with_id(&self, submission: Submission) | Submits a pre-formed Submission, allowing custom IDs for correlation codex-rs/mcp-server/src/codex_tool_runner.rs124 |
next_event | async fn next_event(&self) | Awaits and returns the next event from the agent codex-rs/mcp-server/src/codex_tool_runner.rs206 |
Sources: codex-rs/core/src/codex_thread.rs182-190 codex-rs/mcp-server/src/codex_tool_runner.rs124-206
Op enum taxonomy
Sources: codex-rs/protocol/src/protocol.rs209-510
| Variant | Key Fields | Notes |
|---|---|---|
UserInput | items, thread_settings | Standard input variant used for starting or continuing conversations codex-rs/protocol/src/protocol.rs213-224 |
Interrupt | — | Aborts the current active turn codex-rs/protocol/src/protocol.rs270 |
ExecApproval | id, decision | Responds to a shell command approval request codex-rs/protocol/src/protocol.rs288-292 |
PatchApproval | id, decision | Responds to a file patch approval request codex-rs/protocol/src/protocol.rs294-298 |
Sources: codex-rs/protocol/src/protocol.rs213-224 codex-rs/protocol/src/protocol.rs270 codex-rs/protocol/src/protocol.rs288-298
EventMsg enum taxonomy
Sources: codex-rs/protocol/src/protocol.rs594-1115
| Variant | Key Fields | Notes |
|---|---|---|
TurnStarted | TurnStartedEvent | Signals the beginning of a turn codex-rs/protocol/src/protocol.rs608 |
AgentMessageDelta | AgentMessageDeltaEvent | Streaming assistant text chunk codex-rs/protocol/src/protocol.rs639 |
ExecCommandBegin | ExecCommandBeginEvent | Shell command execution started codex-rs/protocol/src/protocol.rs695 |
ExecApprovalRequest | ExecApprovalRequestEvent | Agent is waiting for user approval to run a command codex-rs/protocol/src/protocol.rs855 |
TurnComplete | TurnCompleteEvent | Turn finished; contains final usage and text codex-rs/protocol/src/protocol.rs620 |
Sources: codex-rs/protocol/src/protocol.rs608-855
The codex-exec mode processes the raw EventMsg stream and translates it into human-readable terminal output.
The EventProcessorWithHumanOutput struct implements the logic for rendering core events into the terminal codex-rs/exec/src/event_processor_with_human_output.rs23-39
Code Entity Space: Event Processing in Exec Mode
Sources: codex-rs/exec/src/event_processor_with_human_output.rs23-97
The codex-app-server translates core EventMsg variants into bespoke server notifications for IDEs and SDKs.
The build_turns_from_rollout_items function converts persisted core RolloutItem entries into the sequence of Turn values used by the app server protocol codex-rs/app-server-protocol/src/protocol/thread_history.rs85-91
| SDK Type | Description |
|---|---|
AgentMessage | Final text response from the agent codex-rs/app-server-protocol/src/protocol/thread_history.rs99-107 |
CommandExecution | Details of a shell command run, including output and status codex-rs/app-server-protocol/src/protocol/thread_history.rs119-136 |
FileChange | Details of a file patch application codex-rs/app-server-protocol/src/protocol/thread_history.rs163-172 |
Sources: codex-rs/app-server-protocol/src/protocol/thread_history.rs85-172
The codex-mcp-server wraps Codex sessions as MCP tools. It maps MCP tools/call requests to core Submission objects and streams EventMsg back as notifications codex-rs/mcp-server/src/codex_tool_runner.rs58-107
Code Entity Space: MCP to Protocol Mapping
Refresh this wiki
This wiki was recently refreshed. Please wait 4 days to refresh again.