codex-cli-sdk

Strongly-typed, async-first Rust SDK for building agents on the OpenAI Codex CLI.

Features

• One-shot queries — query() sends a prompt and returns a collected Turn
• Streaming — query_stream() / thread.run_streamed() yield events as they arrive
• Multi-turn threads — start_thread() / resume_thread() for persistent conversations
• Item lifecycle events — structured ThreadEvent stream (ItemStarted → ItemUpdated → ItemCompleted)
• Approval callbacks — ApprovalCallback for programmatic per-command and per-patch approval
• Sandbox control — SandboxPolicy from Restricted to DangerFullAccess
• Reasoning effort — ReasoningEffort from Minimal to XHigh
• Web search — WebSearchMode (Disabled / Cached / Live)
• Structured output — OutputSchema (inline JSON or file path) for typed responses
• Local providers — point at lmstudio, ollama, or other local models
• Multimodal input — attach image files to any prompt
• Config overrides — pass flat or nested JSON overrides to the CLI via -c key=val
• Stderr callback — capture CLI debug output for logging/diagnostics
• Testing framework — MockTransport, event builders, and fixtures for unit tests without a live CLI
• Cross-platform — macOS, Linux, and Windows

Quick Start

[dependencies]
codex-cli-sdk = "0.1"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }

use codex_cli_sdk::{query, CodexConfig, ThreadOptions};

#[tokio::main]
async fn main() -> codex_cli_sdk::Result<()> {
    let turn = query(
        "List the files in this directory",
        CodexConfig::default(),
        ThreadOptions::default(),
    ).await?;

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

Architecture

                  CodexConfig
                  (cli_path, env, overrides)
                        │
                        ▼
┌─────────────┐   ┌─────────────────┐   ┌─────────────────┐   ┌────────────┐
│  Your Code  │──▶│      Codex      │──▶│  CliTransport   │──▶│ Codex CLI  │
│             │   │                 │   │  (or Mock)      │◀──│            │
│  query()    │   │  start_thread() │   │  stdin/stdout   │   │  JSONL     │
│  query_     │   │  resume_thread()│   └─────────────────┘   │  stdio     │
│  stream()   │   └────────┬────────┘                         └────────────┘
└─────────────┘            │
                           ▼
                   Thread::run()          → Turn
                   Thread::run_streamed() → StreamedTurn (yields ThreadEvents)

Examples

All examples require a working Codex CLI installation (npm install -g @openai/codex).

Core API

One-shot query

use codex_cli_sdk::{query, CodexConfig, ThreadOptions};

let turn = query(
    "Explain the main.rs file",
    CodexConfig::default(),
    ThreadOptions::default(),
).await?;

println!("{}", turn.final_response);
println!("Tokens: in={} out={}",
    turn.usage.as_ref().map_or(0, |u| u.input_tokens),
    turn.usage.as_ref().map_or(0, |u| u.output_tokens),
);

Streaming

use codex_cli_sdk::{query_stream, CodexConfig, ThreadOptions, ThreadEvent, ThreadItem};
use tokio_stream::StreamExt;

let mut stream = query_stream(
    "Refactor the error handling in src/",
    CodexConfig::default(),
    ThreadOptions::default(),
).await?;

while let Some(event) = stream.next().await {
    match event? {
        ThreadEvent::ItemUpdated { item: ThreadItem::AgentMessage { text, .. } } => {
            print!("{text}");
        }
        ThreadEvent::ItemStarted { item: ThreadItem::CommandExecution { command, .. } } => {
            println!("\n> Running: {command}");
        }
        ThreadEvent::ItemCompleted { item: ThreadItem::FileChange { changes, .. } } => {
            for change in &changes {
                println!("  {} {:?}", change.path, change.kind);
            }
        }
        ThreadEvent::TurnCompleted { usage } => {
            println!("\n--- {}/{} tokens ---", usage.input_tokens, usage.output_tokens);
        }
        _ => {}
    }
}

Multi-turn threads

use codex_cli_sdk::{Codex, CodexConfig, ThreadOptions};

let codex = Codex::new(CodexConfig::default())?;

// First turn
let mut thread = codex.start_thread(ThreadOptions::default());
let turn = thread.run("Create a hello.py file", Default::default()).await?;
let thread_id = thread.id().unwrap();

// Resume in a later session
let mut thread = codex.resume_thread(&thread_id, ThreadOptions::default());
let turn = thread.run("Now add error handling to hello.py", Default::default()).await?;

Approval callbacks

use codex_cli_sdk::{Codex, CodexConfig, ThreadOptions};
use codex_cli_sdk::config::ApprovalPolicy;
use codex_cli_sdk::permissions::{ApprovalCallback, ApprovalContext, ApprovalDecision};
use std::sync::Arc;

let options = ThreadOptions::builder()
    .approval(ApprovalPolicy::OnRequest)
    .build();

let callback: ApprovalCallback = Arc::new(|ctx: ApprovalContext| {
    Box::pin(async move {
        println!("Approve command: {}", ctx.request.command);
        if ctx.request.command.starts_with("rm") {
            ApprovalDecision::Denied
        } else {
            ApprovalDecision::Approved
        }
    })
});

let codex = Codex::new(CodexConfig::default())?;
let mut thread = codex
    .start_thread(options)
    .with_approval_callback(callback);

let turn = thread.run("Clean up the build artifacts", Default::default()).await?;

Event Model

run_streamed() yields a sequence of ThreadEvents following this lifecycle:

ThreadStarted
└─ TurnStarted
       ├─ ItemStarted    { item: AgentMessage | CommandExecution | Reasoning | ... }
       │    ItemUpdated  (streaming text deltas)
       │    ItemCompleted
       │
       ├─ ApprovalRequest  ←── responded to via ApprovalCallback
       └─ TurnCompleted { usage }

ThreadItem variants

Advanced Features

Sandbox policy

use codex_cli_sdk::config::SandboxPolicy;

let options = ThreadOptions::builder()
    .sandbox(SandboxPolicy::Restricted)        // read-only
    // .sandbox(SandboxPolicy::WorkspaceWrite) // default — workspace writable
    // .sandbox(SandboxPolicy::DangerFullAccess) // no restrictions
    .build();

Reasoning effort

use codex_cli_sdk::config::ReasoningEffort;

let options = ThreadOptions::builder()
    .reasoning_effort(ReasoningEffort::High)
    .build();

Available levels: Minimal, Low, Medium, High, XHigh.

Structured output

use codex_cli_sdk::config::OutputSchema;

let options = ThreadOptions::builder()
    .output_schema(OutputSchema::Inline(serde_json::json!({
        "type": "object",
        "properties": {
            "summary":       { "type": "string" },
            "files_changed": { "type": "array", "items": { "type": "string" } }
        },
        "required": ["summary", "files_changed"]
    })))
    .build();

An inline schema is automatically written to a temp file and cleaned up after the turn.

Web search

use codex_cli_sdk::config::WebSearchMode;

let options = ThreadOptions::builder()
    .web_search(WebSearchMode::Live)
    .build();

Local providers

let options = ThreadOptions::builder()
    .local_provider("lmstudio") // or "ollama"
    .model("qwen2.5-coder-7b")
    .build();

Config overrides

use codex_cli_sdk::config::ConfigOverrides;

// Nested JSON — auto-flattened to dot-notation `-c key=val` pairs
let config = CodexConfig::builder()
    .config_overrides(ConfigOverrides::Json(serde_json::json!({
        "sandbox_workspace_write": { "network_access": true }
    })))
    .build();

// Or flat key-value pairs
let config = CodexConfig::builder()
    .config_overrides(ConfigOverrides::Flat(vec![
        ("model".into(), "o4-mini".into()),
    ]))
    .build();

Images (multimodal)

use std::path::PathBuf;

let options = ThreadOptions::builder()
    .images(vec![PathBuf::from("screenshot.png")])
    .build();

let turn = thread.run(
    "Describe what you see in this screenshot",
    Default::default(),
).await?;

Stderr debugging

use std::sync::Arc;

let config = CodexConfig::builder()
    .stderr_callback(Arc::new(|line: &str| {
        eprintln!("[codex] {line}");
    }))
    .build();

Cancellation

use tokio_util::sync::CancellationToken;
use codex_cli_sdk::config::TurnOptions;

let cancel = CancellationToken::new();
let turn_opts = TurnOptions { cancel: Some(cancel.clone()), ..Default::default() };

// Cancel from another task:
cancel.cancel();

let result = thread.run_streamed("Long task", turn_opts).await;

CodexConfig Reference

Set any Option<Duration> to None to wait indefinitely.

ThreadOptions Reference

Testing

Enable the testing feature for unit tests without a live CLI:

[dev-dependencies]
codex-cli-sdk = { version = "0.1", features = ["testing"] }

use codex_cli_sdk::testing::{MockTransport, fixtures, builders};

// Use a pre-built fixture
let transport = fixtures::simple_text_response();

// Or assemble events manually
use builders::{thread_started, agent_message_completed, turn_completed};
let mut transport = MockTransport::new();
transport.enqueue_events(vec![
    thread_started("thread-1"),
    agent_message_completed("msg-1", "Hello!"),
    turn_completed(10, 5),
]);

Available fixtures: simple_text_response, tool_call_session, approval_session, error_session, streaming_session, reasoning_session.

Troubleshooting

Feature Flags

Platform Support

macOS, Linux, and Windows.

Disclaimer

This is an unofficial, community-developed SDK and is not affiliated with, endorsed by, or sponsored by OpenAI. "Codex" is a trademark of OpenAI. This crate interacts with the Codex CLI but does not contain any OpenAI proprietary code.

License

Licensed under either of Apache License, Version 2.0 or MIT License at your option.

Maintained by the POM team.