Crate codex_codes 

A tightly typed Rust interface for the OpenAI Codex CLI JSON protocol.

This crate provides type-safe representations of the Codex CLI’s JSONL output, mirroring the structure of the official TypeScript SDK (@openai/codex-sdk).

Message Types

The protocol uses two primary discriminated unions:

• ThreadEvent — Events emitted during thread execution (thread/turn/item lifecycle)
• ThreadItem — Data items representing agent actions (messages, commands, file changes, etc.)

Configuration Types

• ThreadOptions — Per-thread settings (model, sandbox mode, approval policy)
• ApprovalMode, SandboxMode, ModelReasoningEffort, WebSearchMode — Typed enums

Example

use codex_codes::{ThreadEvent, ThreadItem};

let json = r#"{"type":"thread.started","thread_id":"th_abc"}"#;
let event: ThreadEvent = serde_json::from_str(json).unwrap();

Structs

AgentMessageItem

An agent message item containing text output.

CommandExecutionItem

A command execution item.

ErrorItem

An error item.

FileChangeItem

A file change item representing one or more file modifications.

FileUpdateChange

A single file update within a file change item.

ItemCompletedEvent

Event indicating an item has completed.

ItemStartedEvent

Event indicating an item has started processing.

ItemUpdatedEvent

Event indicating an item has been updated.

McpToolCallError

Error from an MCP tool call.

McpToolCallItem

An MCP tool call item.

McpToolCallResult

Result of an MCP tool call.

ReasoningItem

A reasoning item containing the model’s chain-of-thought.

ThreadError

Error information from a thread.

ThreadErrorEvent

A thread-level error event.

ThreadOptions

Per-thread options controlling model, sandbox, and behavior.

ThreadStartedEvent

Event indicating a thread has started.

TodoItem

A single todo entry within a todo list.

TodoListItem

A todo list item.

TurnCompletedEvent

Event indicating a turn has completed successfully.

TurnFailedEvent

Event indicating a turn has failed.

TurnStartedEvent

Event indicating a turn has started.

Usage

Token usage statistics for a completed turn.

WebSearchItem

A web search item.

Enums

ApprovalMode

Approval mode for tool execution.

CommandExecutionStatus

Status of a command execution.

McpToolCallStatus

Status of an MCP tool call.

ModelReasoningEffort

Model reasoning effort level.

PatchApplyStatus

Status of a patch apply operation.

PatchChangeKind

Kind of patch change applied to a file.

SandboxMode

Sandbox mode controlling file system access.

ThreadEvent

All possible events emitted during a Codex thread execution.

ThreadItem

All possible thread item types emitted by the Codex CLI.

WebSearchMode

Web search mode.