Crate codex 

Codex SDK for Rust

Embed Codex in Rust applications by wrapping the codex CLI and exchanging JSONL events over stdin/stdout.

When To Use Which API

• Use Thread::run when you only need the final turn result.
• Use Thread::run_streamed when you need progress events while the turn runs.
• Use Codex::resume_thread when continuing an existing saved thread.

Quickstart

use codex::Codex;

let codex = Codex::new(None)?;
let thread = codex.start_thread(None);
let turn = thread
    .run("Diagnose the test failure and propose a fix", None)
    .await?;

println!("response: {}", turn.final_response);

Continue The Same Thread

use codex::Codex;

let codex = Codex::new(None)?;
let thread = codex.start_thread(None);
let _first = thread.run("Inspect failing tests", None).await?;
let second = thread.run("Apply a fix", None).await?;
println!("{}", second.final_response);

Stream Events

use codex::{Codex, ThreadEvent};
use futures::StreamExt;

let codex = Codex::new(None)?;
let thread = codex.start_thread(None);
let mut events = thread.run_streamed("Analyze repository state", None).await?.events;

while let Some(event) = events.next().await {
    if let ThreadEvent::TurnCompleted { usage } = event? {
        println!("usage: {:?}", usage);
    }
}

Structured Output

use codex::{Codex, TurnOptions};
use serde_json::json;

let codex = Codex::new(None)?;
let thread = codex.start_thread(None);
let schema = json!({
    "type": "object",
    "properties": { "summary": { "type": "string" } },
    "required": ["summary"],
    "additionalProperties": false
});

let turn = thread
    .run(
        "Summarize the repository status",
        Some(TurnOptions {
            output_schema: Some(schema),
            ..Default::default()
        }),
    )
    .await?;
println!("{}", turn.final_response);

Re-exports

pub use codex::Codex;

pub use codex_options::CodexConfigObject;

pub use codex_options::CodexConfigValue;

pub use codex_options::CodexOptions;

pub use errors::Error;

pub use errors::Result;

pub use events::ItemCompletedEvent;

pub use events::ItemStartedEvent;

pub use events::ItemUpdatedEvent;

pub use events::ThreadError;

pub use events::ThreadErrorEvent;

pub use events::ThreadEvent;

pub use events::ThreadStartedEvent;

pub use events::TurnCompletedEvent;

pub use events::TurnFailedEvent;

pub use events::TurnStartedEvent;

pub use events::Usage;

pub use exec::CodexExec;

pub use exec::CodexExecArgs;

pub use items::AgentMessageItem;

pub use items::CommandExecutionItem;

pub use items::CommandExecutionStatus;

pub use items::ErrorItem;

pub use items::FileChangeItem;

pub use items::FileUpdateChange;

pub use items::McpToolCallError;

pub use items::McpToolCallItem;

pub use items::McpToolCallResult;

pub use items::McpToolCallStatus;

pub use items::PatchApplyStatus;

pub use items::PatchChangeKind;

pub use items::ReasoningItem;

pub use items::ThreadItem;

pub use items::TodoItem;

pub use items::TodoListItem;

pub use items::WebSearchItem;

pub use thread::Input;

pub use thread::RunResult;

pub use thread::RunStreamedResult;

pub use thread::Thread;

pub use thread::Turn;

pub use thread::UserInput;

pub use thread_options::ApprovalMode;

pub use thread_options::ModelReasoningEffort;

pub use thread_options::SandboxMode;

pub use thread_options::ThreadOptions;

pub use thread_options::WebSearchMode;

pub use turn_options::TurnOptions;

Modules

codex

High-level client used to start and resume Codex threads.

codex_options

Client-level options, environment configuration, and --config overrides.

errors

Shared error types and Result alias.

events

Stream event payloads emitted by codex exec --experimental-json.

exec

Low-level subprocess execution layer for invoking the Codex CLI.

items

Canonical item payloads produced inside a thread turn.

output_schema_file

Temporary output-schema file helpers for structured output turns.

thread

Thread and turn execution APIs (run and run_streamed).

thread_options

Per-thread execution options mapped to Codex CLI flags/config.

turn_options

Per-turn options such as output schema and cancellation support.

Constants

SDK_VERSION

The version of the Codex Rust SDK, sourced from Cargo.toml.