Crate codex_cli_sdk 

codex-cli-sdk

Rust SDK for the OpenAI Codex CLI.

This crate provides a programmatic interface to the Codex CLI by spawning it as a subprocess and communicating via JSONL. It mirrors the API of the official TypeScript SDK.

Quick Start

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

#[tokio::main]
async fn main() -> codex_cli_sdk::Result<()> {
    let codex = Codex::new(CodexConfig::default())?;
    let mut thread = codex.start_thread(ThreadOptions::default());
    let turn = thread.run("List the files in this directory", Default::default()).await?;
    println!("{}", turn.final_response);
    Ok(())
}

Streaming

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

#[tokio::main]
async fn main() -> codex_cli_sdk::Result<()> {
    let codex = Codex::new(CodexConfig::default())?;
    let mut thread = codex.start_thread(ThreadOptions::default());
    let mut stream = thread.run_streamed("Explain this codebase", Default::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::TurnCompleted { usage } => {
                println!("\n--- done ({} tokens) ---", usage.output_tokens);
            }
            _ => {}
        }
    }
    Ok(())
}

Resuming Threads

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

#[tokio::main]
async fn main() -> codex_cli_sdk::Result<()> {
    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 later
    let mut thread = codex.resume_thread(&thread_id, ThreadOptions::default());
    let turn = thread.run("Now add error handling to hello.py", Default::default()).await?;
    Ok(())
}

Approval Handling

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

#[tokio::main]
async fn main() -> codex_cli_sdk::Result<()> {
    let codex = Codex::new(CodexConfig::default())?;
    let options = ThreadOptions::builder()
        .approval(codex_cli_sdk::config::ApprovalPolicy::OnRequest)
        .build();

    let callback: ApprovalCallback = Arc::new(|ctx| {
        Box::pin(async move {
            println!("Agent wants to run: {}", ctx.request.command);
            ApprovalDecision::Approved.into()
        })
    });

    let mut thread = codex.start_thread(options)
        .with_approval_callback(callback);
    let turn = thread.run("Set up a new Rust project", Default::default()).await?;
    Ok(())
}

Re-exports

pub use callback::EventCallback;

pub use callback::apply_callback;

pub use client::Codex;

pub use client::Thread;

pub use config::ApprovalPolicy;

pub use config::CodexConfig;

pub use config::ReasoningEffort;

pub use config::SandboxPolicy;

pub use config::ThreadOptions;

pub use config::TurnOptions;

pub use config::WebSearchMode;

pub use errors::Error;

pub use errors::Result;

pub use hooks::HookCallback;

pub use hooks::HookContext;

pub use hooks::HookDecision;

pub use hooks::HookEvent;

pub use hooks::HookInput;

pub use hooks::HookMatcher;

pub use hooks::HookOutput;

pub use hooks::HookTimeoutBehavior;

pub use mcp::McpServerConfig;

pub use mcp::McpServers;

pub use permissions::ApprovalCallback;

pub use permissions::ApprovalContext;

pub use permissions::ApprovalDecision;

pub use permissions::ApprovalOutcome;

pub use permissions::PatchApprovalCallback;

pub use permissions::PatchApprovalContext;

pub use types::events::ApprovalRequestEvent;

pub use types::events::PatchApprovalRequestEvent;

pub use types::events::StreamedTurn;

pub use types::events::ThreadError;

pub use types::events::ThreadEvent;

pub use types::events::Turn;

pub use types::events::Usage;

pub use types::input::Input;

pub use types::input::UserInput;

pub use types::items::ThreadItem;

Modules

callback

Event callback — a simple observe/filter hook for SDK consumers.

client

config

errors

hooks

Hook system for observing and reacting to SDK events.

mcp

MCP (Model Context Protocol) server configuration.

permissions

types

Functions

collect_stream

Collect all events from a StreamedTurn into a Vec<ThreadEvent>.

query

One-shot query: start a thread, run the prompt, return all events as a Turn.

query_stream

Streaming query: start a thread, run the prompt, return event stream.