Crate codex

Expand description

Async helper around the OpenAI Codex CLI for programmatic prompting, streaming, apply/diff helpers, and server flows.

Shells out to codex exec, applies sane defaults (non-interactive color handling, timeouts, model hints), and surfaces single-response, streaming, apply/diff, and MCP/app-server helpers.

§Setup: binary + `CODEX_HOME`

Defaults pull CODEX_BINARY or codex on PATH; call CodexClientBuilder::binary (optionally fed by resolve_bundled_binary) to pin an app-bundled binary without touching user installs.
Isolate state with CodexClientBuilder::codex_home (config/auth/history/logs live under that directory) and optionally create the layout with CodexClientBuilder::create_home_dirs. CodexHomeLayout inspects config.toml, auth.json, .credentials.json, history.jsonl, conversations/, and logs/.
CodexHomeLayout::seed_auth_from copies auth.json/.credentials.json from a trusted seed home into an isolated CODEX_HOME without touching history/logs; use AuthSeedOptions to require files or skip missing ones.
AuthSessionHelper checks codex login status and can launch ChatGPT or API key login flows with an app-scoped CODEX_HOME without mutating the parent process env.
Wrapper defaults: temp working dir per call unless working_dir is set, --skip-git-repo-check, 120s timeout (use Duration::ZERO to disable), ANSI colors off, RUST_LOG=error if unset.
Model defaults: gpt-5*/gpt-5.1* (including codex variants) get model_reasoning_effort="medium"/model_reasoning_summary="auto"/model_verbosity="low" to avoid unsupported “minimal” combos.

§Bundled binary (Workstream J)

Apps can ship Codex inside an app-owned bundle rooted at e.g. ~/.myapp/codex-bin/<platform>/<version>/codex; resolve_bundled_binary resolves that path without ever falling back to PATH or CODEX_BINARY. Hosts own downloads and version pins; missing bundles are hard errors.
Pair bundled binaries with per-project CODEX_HOME roots such as ~/.myapp/codex-homes/<project>/, optionally seeding auth.json + .credentials.json from an app-owned seed home. History/logs remain per project; the wrapper still injects CODEX_BINARY/CODEX_HOME per spawn so the parent env stays untouched.
Default behavior remains unchanged until the helper is used; env/CLI defaults stay as documented above.

use codex::CodexClient;
std::env::set_var("CODEX_HOME", "/tmp/my-app-codex");
let client = CodexClient::builder()
    .binary("/opt/myapp/bin/codex")
    .model("gpt-5-codex")
    .timeout(Duration::from_secs(45))
    .build();
let reply = client.send_prompt("Health check").await?;
println!("{reply}");

Surfaces:

CodexClient::send_prompt for a single prompt/response with optional --json output.
CodexClient::stream_exec for typed, real-time JSONL events from codex exec --json, returning an ExecStream with an event stream plus a completion future.
CodexClient::apply / CodexClient::diff to run codex apply <TASK_ID> and codex cloud diff <TASK_ID>, echo stdout/stderr according to the builder (mirror_stdout / quiet), and return captured output + exit status.
CodexClient::generate_app_server_bindings to refresh app-server protocol bindings via codex app-server generate-ts (optional --prettier) or generate-json-schema, returning captured stdout/stderr plus the exit status.
CodexClient::run_sandbox to wrap codex sandbox <platform> (macOS/Linux/Windows), pass --full-auto/--log-denials/--config/--enable/--disable, and return the inner command status + output. macOS is the only platform that emits denial logs; Linux depends on the bundled codex-linux-sandbox; Windows sandboxing is experimental and relies on the upstream helper (no capability gating—non-zero exits bubble through).
CodexClient::check_execpolicy to evaluate shell commands against Starlark execpolicy files with repeatable --policy flags, optional pretty JSON, and parsed decision output (allow/prompt/forbidden or noMatch).
CodexClient::list_features to wrap codex features list with optional --json parsing, shared config/profile overrides, and parsed feature entries (name/stage/enabled).
CodexClient::start_responses_api_proxy to launch the codex responses-api-proxy helper with an API key piped via stdin plus optional port/server-info/upstream/shutdown flags.
CodexClient::stdio_to_uds to spawn codex stdio-to-uds <SOCKET_PATH> with piped stdio so callers can bridge Unix domain sockets manually.

§Streaming, events, and artifacts

.json(true) requests JSONL streaming. Expect thread.started/thread.resumed, turn.started/turn.completed/turn.failed, and item.created/item.updated with item.type such as agent_message, reasoning, command_execution, file_change, mcp_tool_call, web_search, or todo_list plus optional status/content/input. Errors surface as {"type":"error","message":...}.
Sample payloads ship with the streaming examples (crates/codex/examples/fixtures/*); most examples support --sample for offline inspection.
Disable mirror_stdout when parsing JSON so stdout stays under caller control; quiet controls stderr mirroring. json_event_log tees raw JSONL lines to disk before parsing; idle_timeout, output_last_message, and output_schema cover artifact handling.
crates/codex/examples/stream_events.rs, stream_last_message.rs, stream_with_log.rs, and json_stream.rs cover typed consumption, artifact handling, log teeing, and minimal streaming.

§Resume + apply/diff

codex exec --json resume --last [-] streams the same thread/turn/item events as codex exec --json but starts from an existing session (thread.resumed).
Apply/diff require task IDs: codex apply <TASK_ID> applies a diff, and codex cloud diff <TASK_ID> prints a cloud task diff when supported by the binary.
Convenience: CodexClient::apply / CodexClient::diff will append <TASK_ID> from CODEX_TASK_ID when set; otherwise they still spawn the command and return the non-zero exit status/output from the CLI.
crates/codex/examples/resume_apply.rs shows a CLI-native resume/apply flow and ships --sample fixtures for offline inspection.

§Servers and capability detection

Integrate the stdio servers via codex mcp-server / codex app-server (crates/codex/examples/mcp_codex_flow.rs, mcp_codex_tool.rs, mcp_codex_reply.rs, app_server_turns.rs, app_server_thread_turn.rs) to drive JSON-RPC flows, approvals, and shutdown.
probe_capabilities and the feature_detection example focus on --output-schema, --add-dir, codex login --mcp, and codex features list availability; other subcommand drift (like cloud-only commands) is surfaced by the parity snapshot/reports in cli_manifests/codex/.

More end-to-end flows and CLI mappings live in crates/codex/README.md and crates/codex/EXAMPLES.md.

§Capability/versioning surfaces (Workstream F)

probe_capabilities captures --version, features list, and --help hints into a CodexCapabilities snapshot with collected_at timestamps and BinaryFingerprint metadata keyed by canonical binary path.
Guard helpers (guard_output_schema, guard_add_dir, guard_mcp_login, guard_features_list) keep optional flags disabled when support is unknown and return operator-facing notes for unsupported features.
Cache controls: CapabilityCachePolicy::{PreferCache, Refresh, Bypass} plus builder helpers steer cache reuse. Use Refresh for TTL/backoff windows or hot-swaps that reuse the same binary path; use Bypass when metadata is missing (FUSE/overlay filesystems) or when you need an isolated probe.
TTL/backoff helper: capability_cache_ttl_decision inspects collected_at to suggest when to reuse, refresh, or bypass cached snapshots and stretches the recommended policy when metadata is missing.
Overrides + persistence: capability_snapshot, capability_overrides, write_capabilities_snapshot, read_capabilities_snapshot, and capability_snapshot_matches_binary let hosts reuse snapshots across processes and fall back to probes when fingerprints diverge.

Re-exports§

pub use jsonl::thread_event_jsonl_file;
pub use jsonl::thread_event_jsonl_reader;
pub use jsonl::JsonlThreadEventParser;
pub use jsonl::ThreadEventJsonlFileReader;
pub use jsonl::ThreadEventJsonlReader;
pub use jsonl::ThreadEventJsonlRecord;
pub use rollout_jsonl::find_rollout_file_by_id;
pub use rollout_jsonl::find_rollout_files;
pub use rollout_jsonl::rollout_jsonl_file;
pub use rollout_jsonl::rollout_jsonl_reader;
pub use rollout_jsonl::RolloutBaseInstructions;
pub use rollout_jsonl::RolloutContentPart;
pub use rollout_jsonl::RolloutEvent;
pub use rollout_jsonl::RolloutEventMsg;
pub use rollout_jsonl::RolloutEventMsgPayload;
pub use rollout_jsonl::RolloutJsonlError;
pub use rollout_jsonl::RolloutJsonlFileReader;
pub use rollout_jsonl::RolloutJsonlParser;
pub use rollout_jsonl::RolloutJsonlReader;
pub use rollout_jsonl::RolloutJsonlRecord;
pub use rollout_jsonl::RolloutResponseItem;
pub use rollout_jsonl::RolloutResponseItemPayload;
pub use rollout_jsonl::RolloutSessionMeta;
pub use rollout_jsonl::RolloutSessionMetaPayload;
pub use rollout_jsonl::RolloutUnknown;

Modules§

jsonl
mcp: Launch and interact with Codex MCP + app servers using stored runtime definitions.
rollout_jsonl
wrapper_coverage_manifest

Structs§

AppServerCodegenOutput: Captured output from app-server codegen commands.
AppServerCodegenRequest: Request for codex app-server generate-ts or generate-json-schema.
ApplyDiffArtifacts: Captured output from task-oriented subcommands such as codex apply <TASK_ID> or codex cloud diff <TASK_ID>.
AuthSeedOptions: Options controlling how auth files are seeded from a trusted home.
AuthSeedOutcome: Result of seeding Codex auth files into a target home.
AuthSessionHelper: Helper for checking Codex auth state and triggering login flows with an app-scoped CODEX_HOME.
BinaryFingerprint: File metadata used to invalidate cached capability snapshots when the binary changes.
BundledBinary: Resolved bundled Codex binary details.
BundledBinarySpec: Specification for resolving an app-bundled Codex binary.
CapabilityCacheKey: Cache key for capability snapshots derived from a specific Codex binary path.
CapabilityFeatureOverrides: Optional overrides for feature detection that can be layered onto probe results.
CapabilityGuard: Result of gating a Codex feature/flag against probed capabilities.
CapabilityOverrides: Caller-supplied capability data that can short-circuit or adjust probing. Manual snapshots override cached/probed data, and feature/version overrides apply on top of whichever snapshot is returned.
CapabilityProbePlan: Description of how we interrogate the CLI to populate a CodexCapabilities snapshot.
CapabilityTtlDecision: Result of applying a TTL/backoff window to a capability snapshot.
CliOverrides: Builder-scoped CLI overrides.
CliOverridesPatch: Request-level overlay of builder overrides.
CloudApplyRequest: Request for codex cloud apply [--attempt N] <TASK_ID>.
CloudDiffRequest: Request for codex cloud diff [--attempt N] <TASK_ID>.
CloudExecRequest: Request for codex cloud exec.
CloudListOutput: Output from codex cloud list.
CloudListRequest: Request for codex cloud list.
CloudOverviewRequest: Request for codex cloud (overview/help).
CloudStatusRequest: Request for codex cloud status <TASK_ID>.
CodexCapabilities: Snapshot of Codex CLI capabilities derived from probing a specific binary.
CodexClient: High-level client for interacting with codex exec.
CodexClientBuilder: Builder for crate::CodexClient.
CodexFeature: Single feature entry reported by codex features list.
CodexFeatureFlags: Feature gates for Codex CLI flags.
CodexHomeLayout: Describes the on-disk layout used by the Codex CLI when CODEX_HOME is set.
CodexLatestReleases: Caller-supplied table of known latest Codex releases.
CodexRelease: Release metadata for a specific Codex build channel.
CodexUpdateAdvisory: Update guidance derived from comparing local and latest Codex versions.
CodexVersionInfo: Parsed version details emitted by codex --version.
CommandExecutionDelta: Streaming delta for command execution.
CommandExecutionState: Snapshot of a command execution, including accumulated stdout/stderr.
ConfigOverride: Represents a single --config key=value override.
DebugAppServerHelpRequest: Request for codex debug app-server help [COMMAND]....
DebugAppServerRequest: Request for codex debug app-server.
DebugAppServerSendMessageV2Request: Request for codex debug app-server send-message-v2 <USER_MESSAGE>.
DebugCommandRequest: Request for codex debug.
DebugHelpRequest: Request for codex debug help [COMMAND]....
EventError: Error payload shared by turn/item failures.
ExecCompletion: Summary returned when the codex child process exits.
ExecPolicyCheckRequest: Request to evaluate a command against Starlark execpolicy files.
ExecPolicyCheckResult: Captured output from codex execpolicy check.
ExecPolicyEvaluation: Parsed output from codex execpolicy check.
ExecPolicyMatch: Matched execpolicy summary with the merged decision and contributing rules.
ExecPolicyNoMatch: Response returned when no rules matched.
ExecPolicyRuleMatch: Matched rule entry returned by codex execpolicy check.
ExecRequest: Options configuring a single exec request.
ExecReviewCommandRequest: Request for codex exec review [OPTIONS] [PROMPT].
ExecStream: Ergonomic container for the streaming surface; produced by stream_exec (implemented in D2).
ExecStreamControl: Control-capable variant of ExecStream, providing a best-effort termination hook.
ExecStreamRequest: Options configuring a streaming exec invocation.
ExecTerminationHandle
FeatureToggles: Feature toggles forwarded to --enable/--disable.
FeaturesCommandRequest: Request for codex features.
FeaturesDisableRequest: Request for codex features disable <FEATURE>.
FeaturesEnableRequest: Request for codex features enable <FEATURE>.
FeaturesListOutput: Parsed output from codex features list.
FeaturesListRequest: Request for codex features list.
FileChangeDelta: Streaming delta describing a file change.
FileChangeState: File change or diff applied by the agent.
ForkSessionRequest: Request for codex fork [OPTIONS] [SESSION_ID] [PROMPT].
HelpCommandRequest: Request for codex <scope> help [COMMAND]....
ItemDelta: Streaming delta describing the next piece of an item.
ItemEnvelope: Shared wrapper for item events that always include thread/turn context.
ItemFailure: Terminal item failure event.
ItemSnapshot: Snapshot of an item at start/completion time.
McpAddRequest: Request for codex mcp add.
McpGetRequest: Request for codex mcp get <NAME>.
McpListOutput: Output from codex mcp list.
McpListRequest: Request for codex mcp list.
McpLogoutRequest: Request for codex mcp logout <NAME>.
McpOauthLoginRequest: Request for codex mcp login <NAME> (OAuth).
McpOverviewRequest: Request for codex mcp (overview/help).
McpRemoveRequest: Request for codex mcp remove <NAME>.
McpToolCallDelta: Streaming delta for MCP tool call output.
McpToolCallState: State of an MCP tool call.
ReasoningOverrides: Structured reasoning overrides converted into config entries.
ResponsesApiProxyHandle: Running responses proxy process and metadata.
ResponsesApiProxyInfo: Parsed {port,pid} emitted by codex responses-api-proxy --server-info.
ResponsesApiProxyRequest: Request for codex responses-api-proxy.
ResumeRequest: Options configuring a streaming resume invocation.
ResumeSessionRequest: Request for codex resume [OPTIONS] [SESSION_ID] [PROMPT].
ReviewCommandRequest: Request for codex review [OPTIONS] [PROMPT].
SandboxCommandRequest: Request to run an arbitrary command inside a Codex-provided sandbox.
SandboxRun: Captured output from codex sandbox <platform>.
StdioToUdsRequest: Request for codex stdio-to-uds <SOCKET_PATH>.
TextContent: Human-readable content emitted by the agent.
TextDelta: Incremental content fragment for streaming items.
ThreadStarted: Marks the start of a new thread.
TodoItem: Single todo item.
TodoListDelta: Streaming delta for todo list mutations.
TodoListState: Checklist maintained by the agent.
TurnCompleted: Reports a completed turn.
TurnFailed: Indicates a turn-level failure.
TurnStarted: Indicates the CLI accepted a new turn within a thread.
WebSearchDelta: Streaming delta for search results.
WebSearchState: Details of a web search step.

Enums§

AppServerCodegenTarget: Target for app-server code generation.
ApprovalPolicy: Approval policy used by --ask-for-approval.
AuthSeedError: Errors that may occur while seeding Codex auth files into a target home.
BundledBinaryError: Errors that may occur while resolving a bundled Codex binary.
CapabilityCachePolicy: Cache interaction policy for capability probes.
CapabilityFeature: Feature/flag tokens that can be guarded based on probed capabilities.
CapabilityProbeStep: Command-level probes used to infer feature support.
CapabilitySnapshotError: Errors encountered while saving or loading capability snapshots.
CapabilitySnapshotFormat: Supported serialization formats for capability snapshots and overrides.
CapabilitySupport: High-level view of whether a specific feature can be used safely.
CodexAuthMethod: Authentication mechanism used to sign in.
CodexAuthStatus: Current authentication state reported by codex login status.
CodexError: Errors that may occur while invoking the Codex CLI.
CodexFeatureStage: Stage labels reported by codex features list.
CodexLogoutStatus: Result of invoking codex logout.
CodexReleaseChannel: Release channel segments inferred from the Codex version string.
CodexUpdateStatus: Enum summarizing whether an update is needed based on provided release data.
ColorMode: ANSI color behavior for codex exec output.
ExecPolicyDecision: Decision returned by execpolicy evaluation.
ExecStreamError: Errors that may occur while consuming the JSONL stream.
FeaturesListFormat: Format used to parse codex features list output.
FileChangeKind: Type of file operation being reported.
FlagState: Three-state flag used when requests can override builder defaults.
HelpScope: Selector for codex help-style command families.
ItemDeltaPayload: Delta form of an item payload. Each delta should be applied in order to reconstruct the item.
ItemPayload: Fully-typed item payload for start/completed events.
ItemStatus: Item status supplied by the CLI for bookkeeping.
LocalProvider: Local provider selection for OSS backends.
McpAddTransport: Transport for codex mcp add.
ModelVerbosity: Config values for model_verbosity.
ReasoningEffort: Config values for model_reasoning_effort.
ReasoningSummary: Config values for model_reasoning_summary.
ReasoningSummaryFormat: Config values for model_reasoning_summary_format.
ResumeSelector: Selector for codex resume targets.
SafetyOverride: Safety overrides that collapse approval/sandbox behavior.
SandboxMode: Sandbox isolation level.
SandboxPlatform: Sandbox platform variant; maps to platform subcommands of codex sandbox.
ThreadEvent: Single JSONL event emitted by codex exec --json.
ToolCallStatus: Lifecycle state for a tool call.
WebSearchStatus: Search progress indicator.

Functions§

capability_cache_entries: Returns all capability cache entries keyed by canonical binary path.
capability_cache_entry: Returns the cached capabilities for a specific binary path if present.
capability_cache_ttl_decision: Decides whether a cached capability snapshot should be refreshed based on collected_at.
capability_snapshot_matches_binary: True when the snapshot was captured for the same binary path and fingerprint.
clear_capability_cache: Clears all cached capability snapshots.
clear_capability_cache_entry: Removes the cached capabilities for a specific binary. Returns true when an entry was removed.
default_bundled_platform_label: Default bundled platform label for the current target (e.g., darwin-arm64, linux-x64, windows-x64).
deserialize_capabilities_snapshot: Parses a capability snapshot from serialized JSON or TOML.
deserialize_capability_overrides: Parses capability overrides from serialized JSON or TOML.
read_capabilities_snapshot: Loads a capability snapshot from disk, inferring format from the file extension when absent.
read_capability_overrides: Reads capability overrides from disk, inferring format from the file extension when absent.
resolve_bundled_binary: Resolves a bundled Codex binary under <bundle_root>/<platform>/<version>/.
serialize_capabilities_snapshot: Serializes a capability snapshot to a JSON or TOML string.
serialize_capability_overrides: Serializes capability overrides (snapshot, version, feature flags) to a JSON or TOML string.
update_advisory_from_capabilities: Computes an update advisory for a previously probed binary.
write_capabilities_snapshot: Writes a capability snapshot to disk, inferring format from the file extension when absent.
write_capability_overrides: Writes capability overrides to disk, inferring format from the file extension when absent.

Type Aliases§

DynExecCompletion: Type-erased completion future that resolves when streaming stops.
DynThreadEventStream: Type-erased stream of events from the Codex CLI.

Crate codex

Crate codex Copy item path

§Setup: binary + CODEX_HOME

§Bundled binary (Workstream J)

§Streaming, events, and artifacts

§Resume + apply/diff

§Servers and capability detection

§Capability/versioning surfaces (Workstream F)

Re-exports§

Modules§

Structs§

Enums§

Functions§

Type Aliases§

Crate codex

§Setup: binary + `CODEX_HOME`