codex/
lib.rs

1//! # Codex SDK for Rust
2//!
3//! Embed Codex in Rust applications by wrapping the `codex` CLI and exchanging
4//! JSONL events over stdin/stdout.
5//!
6//! ## When To Use Which API
7//!
8//! - Use [`Thread::run`] when you only need the final turn result.
9//! - Use [`Thread::run_streamed`] when you need progress events while the turn runs.
10//! - Use [`Codex::resume_thread`] when continuing an existing saved thread.
11//!
12//! ## Quickstart
13//!
14//! ```rust,no_run
15//! use codex::Codex;
16//!
17//! # async fn example() -> codex::Result<()> {
18//! let codex = Codex::new(None)?;
19//! let thread = codex.start_thread(None);
20//! let turn = thread
21//!     .run("Diagnose the test failure and propose a fix", None)
22//!     .await?;
23//!
24//! println!("response: {}", turn.final_response);
25//! # Ok(())
26//! # }
27//! ```
28//!
29//! ## Continue The Same Thread
30//!
31//! ```rust,no_run
32//! use codex::Codex;
33//!
34//! # async fn example() -> codex::Result<()> {
35//! let codex = Codex::new(None)?;
36//! let thread = codex.start_thread(None);
37//! let _first = thread.run("Inspect failing tests", None).await?;
38//! let second = thread.run("Apply a fix", None).await?;
39//! println!("{}", second.final_response);
40//! # Ok(())
41//! # }
42//! ```
43//!
44//! ## Stream Events
45//!
46//! ```rust,no_run
47//! use codex::{Codex, ThreadEvent};
48//! use futures::StreamExt;
49//!
50//! # async fn example() -> codex::Result<()> {
51//! let codex = Codex::new(None)?;
52//! let thread = codex.start_thread(None);
53//! let mut events = thread.run_streamed("Analyze repository state", None).await?.events;
54//!
55//! while let Some(event) = events.next().await {
56//!     if let ThreadEvent::TurnCompleted { usage } = event? {
57//!         println!("usage: {:?}", usage);
58//!     }
59//! }
60//! # Ok(())
61//! # }
62//! ```
63//!
64//! ## Structured Output
65//!
66//! ```rust,no_run
67//! use codex::{Codex, TurnOptions};
68//! use serde_json::json;
69//!
70//! # async fn example() -> codex::Result<()> {
71//! let codex = Codex::new(None)?;
72//! let thread = codex.start_thread(None);
73//! let schema = json!({
74//!     "type": "object",
75//!     "properties": { "summary": { "type": "string" } },
76//!     "required": ["summary"],
77//!     "additionalProperties": false
78//! });
79//!
80//! let turn = thread
81//!     .run(
82//!         "Summarize the repository status",
83//!         Some(TurnOptions {
84//!             output_schema: Some(schema),
85//!             ..Default::default()
86//!         }),
87//!     )
88//!     .await?;
89//! println!("{}", turn.final_response);
90//! # Ok(())
91//! # }
92//! ```
93
94/// High-level client used to start and resume Codex threads.
95pub mod codex;
96/// Client-level options, environment configuration, and `--config` overrides.
97pub mod codex_options;
98/// Shared error types and `Result` alias.
99pub mod errors;
100/// Stream event payloads emitted by `codex exec --experimental-json`.
101pub mod events;
102/// Low-level subprocess execution layer for invoking the Codex CLI.
103pub mod exec;
104/// Canonical item payloads produced inside a thread turn.
105pub mod items;
106/// Temporary output-schema file helpers for structured output turns.
107pub mod output_schema_file;
108/// Thread and turn execution APIs (`run` and `run_streamed`).
109pub mod thread;
110/// Per-thread execution options mapped to Codex CLI flags/config.
111pub mod thread_options;
112/// Per-turn options such as output schema and cancellation support.
113pub mod turn_options;
114
115pub use codex::Codex;
116pub use codex_options::{CodexConfigObject, CodexConfigValue, CodexOptions};
117pub use errors::{Error, Result};
118pub use events::{
119    ItemCompletedEvent, ItemStartedEvent, ItemUpdatedEvent, ThreadError, ThreadErrorEvent,
120    ThreadEvent, ThreadStartedEvent, TurnCompletedEvent, TurnFailedEvent, TurnStartedEvent, Usage,
121};
122pub use exec::{CodexExec, CodexExecArgs};
123pub use items::{
124    AgentMessageItem, CommandExecutionItem, CommandExecutionStatus, ErrorItem, FileChangeItem,
125    FileUpdateChange, McpToolCallError, McpToolCallItem, McpToolCallResult, McpToolCallStatus,
126    PatchApplyStatus, PatchChangeKind, ReasoningItem, ThreadItem, TodoItem, TodoListItem,
127    WebSearchItem,
128};
129pub use thread::{Input, RunResult, RunStreamedResult, Thread, Turn, UserInput};
130pub use thread_options::{
131    ApprovalMode, ModelReasoningEffort, SandboxMode, ThreadOptions, WebSearchMode,
132};
133pub use turn_options::TurnOptions;
134
135/// The version of the Codex Rust SDK, sourced from `Cargo.toml`.
136pub const SDK_VERSION: &str = env!("CARGO_PKG_VERSION");
codex/lib.rs

codex/
lib.rs
