Modules
Public entry point for the Codex SDK.
Defines a reusable agent with instructions, tools, and hooks.
Multi-turn runner that orchestrates agent execution over Codex threads.
App-server transport for stateful, bidirectional communication with Codex.
MCP (Model Context Protocol) server management for app-server connections.
Legacy v1 app-server endpoints for compatibility with older servers.
Error returned when an approval policy denies a tool invocation.
Approval helpers invoked by the auto-run pipeline when actions require consent.
Behaviour for implementing pluggable approval hooks.
ETS-based registry for tracking async approval requests.
Simple allow/deny approval policy used for tests and defaults.
API key resolution with CODEX_API_KEY → auth.json → OPENAI_API_KEY precedence.
Thin wrapper around the upstream codex terminal client.
Raw codex CLI subprocess session backed by CliSubprocessCore.Channel.
Base URL resolution with option → env → default precedence.
Single source of truth for all Codex SDK default configuration values.
Shared validation for reasoning summary, verbosity, and history persistence.
Config override serialization, nested map flattening, and TOML value validation.
Base error struct for Codex failures.
Typed event structs emitted during Codex turn execution.
Event emitted when account login completes.
Event emitted when account rate limits are updated.
Event emitted when account authentication state changes.
Event emitted when the app catalog changes.
Lossless wrapper for an app-server notification that is not yet mapped into a typed event.
Event emitted when the app-server asks the client to refresh ChatGPT auth tokens.
Collab event emitted when an agent interaction starts.
Collab event emitted when an agent interaction completes.
Collab event emitted when an agent spawn starts.
Collab event emitted when an agent spawn completes.
Collab event emitted when a collab session begins closing.
Collab event emitted when a collab session closes.
Collab event emitted when an agent resume begins.
Collab event emitted when an agent resume completes.
Collab event emitted when an agent begins waiting.
Collab event emitted when an agent stops waiting.
Event emitted when the app-server requests approval for a command execution.
Event delta emitted while a command execution is producing output.
Event emitted when configuration warnings are reported.
Indicates that the conversation context was compacted.
Event emitted when the server reports a deprecated feature or behavior.
Event emitted when the app-server asks the client to execute a dynamic tool call.
Event emitted for MCP elicitation requests.
Event emitted when a review session starts.
General error event emitted by the CLI.
Event emitted when a review session ends.
Event emitted when the app-server requests approval for a file change.
Event delta emitted while a file change stream is producing output.
Event emitted when a fuzzy file search session finishes.
Event emitted when a fuzzy file search session publishes updated matches.
Review payload emitted by guardian auto-approval review notifications.
Event emitted when guardian review completes for an approval request.
Event emitted when guardian review begins for an approval request.
Event emitted when an app-server hook run completes.
Event emitted when an app-server hook run starts.
Event delta emitted when the agent produces message content.
Event emitted when an item completes.
Event delta emitted for user input text items.
Event emitted when an item begins processing.
Event emitted when an in-progress item receives an update.
Event emitted when the app-server requests an MCP elicitation response from the client.
Event emitted when an MCP server OAuth login completes.
Event emitted when app-server observes an MCP server startup state transition.
Summary of MCP server startup completion.
Incremental status update for MCP server startup.
Progress message emitted while an MCP tool call is running.
Event emitted when Codex reroutes a turn to a different model.
Event emitted when the app-server requests additional permissions from the client.
Event emitted when a raw response item completes on the app-server stream.
Event delta emitted while reasoning content is streaming.
Event delta emitted while reasoning summary text is streaming.
Event emitted when a new reasoning summary part is added.
Event emitted when the agent requests user input.
Event emitted when the app-server resolves a prior server request.
Event emitted when a session is configured.
Event emitted when the agent shuts down.
Invalidation signal emitted when watched skill metadata changes.
Event emitted when stdin is written to an interactive command execution.
Event emitted when a thread is archived.
Event emitted when the thread display name changes.
Event emitted when thread realtime closes.
Event emitted when thread realtime encounters an error.
Event emitted when thread realtime adds a non-audio item.
Event emitted when thread realtime streams output audio.
Event emitted when thread realtime startup is accepted.
Indicates that recent user turns were removed from context.
Event emitted when a thread is first created.
Event emitted when thread load or activity status changes.
Incremental token usage update emitted while a turn is in flight.
Event emitted when a thread is restored from the archive.
Event emitted when a tool call has completed and returned output.
Indicates Codex requires a tool invocation to continue auto-run.
Event emitted when a turn is aborted.
Signals that Codex compacted a turn's history.
Final event for a turn, optionally carrying final response and usage data.
Signals that a continuation token is available for resuming the turn.
Event emitted when the app-server publishes a turn diff update.
Event emitted when a turn fails.
Event emitted when the app-server publishes an updated plan for the current turn.
Event emitted when a new turn starts.
Event emitted when an undo operation completes.
Event emitted when an undo operation begins.
Warning event emitted during a turn.
Event emitted when world-writable Windows paths are detected.
Process manager wrapping the codex binary via the shared CLI subprocess core.
Configuration for file search capabilities in threads and runs.
Attachment staging helpers mirroring the Python SDK file APIs.
Represents a staged file attachment.
GenServer-backed manifest that tracks staged file attachments, deduplicates by checksum,
and prunes expired entries on a schedule. This powers the public Codex.Files helpers.
Convenience macro for defining function-backed tools with JSON schemas.
Represents an input or output guardrail invoked around agent execution.
Error raised when a guardrail rejects or trips during execution.
HTTP client abstraction for making HTTP requests.
Mock HTTP client for testing.
HTTP client implementation using Req.
Represents a handoff from one agent to another, wrapping the downstream agent as a tool with optional input filtering and history nesting controls.
Carries conversation history and run context into handoff input filters.
Shared helpers for newline-delimited subprocess output buffering and JSON decoding.
Typed representations of thread items emitted by the Codex runtime.
Assistant-authored message item emitted by the Codex runtime, with optional parsed payloads for structured output experiments.
Represents a collaboration tool call between agents.
Captures an execution request made by the agent, including aggregated output and status metadata.
Raw response item emitted when compaction summaries are generated.
Marker item emitted when context compaction occurred.
Metadata describing a dynamic tool invocation handled outside the static tool registry.
Normalised error record describing failures surfaced during a turn.
Represents a file diff emitted by the agent, including per-path change metadata and completion status.
Raw response item describing a ghost snapshot captured for undo.
Image generation result item emitted by the app-server.
An image view event emitted by the app-server when it renders a local image.
Metadata describing a tool invocation routed through an MCP server.
Planning item emitted when the agent publishes a plan as a first-class thread item.
Fallback container for unparsed raw response items.
Intermediate reasoning trace shared as part of tool or agent transparency.
Indicates that review mode has been entered or exited.
Structured checklist shared by the agent to track outstanding follow-up items.
User-authored message item carrying a list of input blocks.
Records a web search request issued by the agent, preserving the original query.
MCP JSON-RPC client for stdio and streamable HTTP transports.
Helpers for managing MCP server configuration through app-server config APIs.
Stores and refreshes OAuth credentials for streamable HTTP MCP servers.
Runs MCP servers over stdio using the core JSON-RPC protocol session stack.
Implements MCP JSON-RPC over HTTP with optional bearer or OAuth auth.
Model tuning options and provider selection used to configure codex runs.
Codex model metadata projected from cli_subprocess_core.
Shared custom CA bundle resolution for subprocesses and outbound TLS clients.
Native OAuth login and session management for Codex.
Summary returned by Codex.OAuth.login/1 and Codex.OAuth.await_login/2.
Internal OAuth session structs shared across flows and token stores.
Pending device-code OAuth login state returned by Codex.OAuth.begin_login/1.
Pending browser-based OAuth login state returned by Codex.OAuth.begin_login/1.
Current OAuth auth state returned by Codex.OAuth.status/1 and refresh/1.
Global configuration for Codex interactions.
Persists structured output schemas to temporary JSON files so they can be passed to the Codex CLI. Returns the generated path alongside a cleanup function for RAII-style usage.
Local plugin authoring helpers for manifests, marketplaces, and scaffold flows.
Local authoring model for .codex-plugin/plugin.json.
Local authoring model for .agents/plugins/marketplace.json.
Canonical local authoring paths for plugin manifests and marketplaces.
Custom prompt discovery and expansion helpers.
Byte range for text element positioning.
Typed reference to a collaboration agent thread.
Typed representation of a collaboration agent lifecycle state.
Typed association between an agent reference and its lifecycle state.
Collaboration mode configuration with presets.
Protocol configuration type enums and converters.
MCP elicitation request and action types.
MCP elicitation request
Encoders for Codex protocol operations submitted to the runtime.
Typed app-server plugin request and response models.
Plugin app metadata returned by plugin/read and plugin/install.
Plugin auth policy values returned by the app-server plugin APIs.
Plugin detail payload returned by plugin/read.
Typed params for plugin/install.
Plugin install policy values returned by the app-server plugin APIs.
Typed response for plugin/install.
Plugin presentation metadata returned on plugin summary/detail responses.
Typed params for plugin/list.
Typed response for plugin/list.
Marketplace entries returned by plugin/list.
Marketplace interface metadata surfaced by plugin/list.
Marketplace load failure details returned by plugin/list.
Typed params for plugin/read.
Typed response for plugin/read.
Plugin skill metadata returned by plugin/read.
Plugin source metadata returned by the app-server plugin APIs.
Plugin summary metadata returned by plugin/list and plugin/read.
Typed params for plugin/uninstall.
Typed response for plugin/uninstall.
Rate limit snapshot types for TokenCount events.
Credits balance snapshot
Complete rate limit snapshot
A rate limit window
Types for app-server request-permissions approval requests and responses.
Additional filesystem permissions requested or granted for a turn or session.
Additional macOS permissions requested for a turn or session.
Additional network permissions requested or granted for a turn or session.
Additional macOS permissions granted for a turn or session.
Permission profile included in request-permissions approval responses.
Scope applied to granted permissions in a permissions approval response.
Permission profile included in request-permissions approval requests.
Structured response for an app-server permissions approval request.
Types for agent-to-user input requests.
An answer to a question
An option for a question
A question to present to the user
Response containing answers to all questions
Typed representation of thread/session source metadata returned by Codex.
Typed representation of sub-agent session source metadata.
Text element with byte range for rich text input.
Rate limit detection and handling utilities.
Realtime audio streaming with OpenAI's Realtime API.
A realtime agent optimized for voice interactions.
Audio format utilities for realtime sessions.
Configuration types for realtime sessions.
Settings for output guardrails.
Options for connecting to a realtime model.
Configuration for input audio noise reduction.
Configuration for running a realtime agent session.
Model settings for a realtime session.
Configuration for request tracing.
Configuration for input audio transcription.
Configuration for voice activity detection and turn-taking.
Diagnostics helpers for OpenAI Realtime sessions.
High-level session events for realtime applications.
An agent has ended.
A new agent has started.
Audio generation ended.
Audio data received.
Audio was interrupted.
Error occurred.
Common information for all events.
Guardrail was tripped.
Agent handed off to another agent.
Item added to history.
Full history update.
Input audio timeout triggered.
Raw model event wrapper.
Tool call completed.
Tool call started.
Conversation item types for realtime sessions.
Audio content from assistant.
An assistant message item.
Text content from assistant.
Audio input content.
Image input content.
Text input content.
A tool/function call item.
A system message item.
A user message item.
Behaviour for realtime model implementations.
Low-level events from the realtime model transport layer.
Audio generation completed for an item.
Raw audio bytes from the model.
Audio was interrupted.
Connection status change event.
Transport-layer error event.
Exception during model operation.
Input audio timeout triggered.
Input audio transcription completed.
Item deleted from history.
Item added to the history or updated.
Catchall for vendor-specific events.
Raw event forwarded from server.
Model attempted a tool/function call.
Partial transcript update.
Model finished generating a response.
Model started generating a response.
Input message types for sending events to the realtime model.
Send audio data to the model.
Send an interrupt to the model.
Send a raw message to the model.
Send session settings update.
Send tool output to the model.
Send user input (text or structured message).
WebSocket client for OpenAI Realtime API.
Tracks audio playback progress for handling interruptions.
Orchestrates realtime agent sessions.
Manages a realtime session with WebSocket connection.
Retry logic with configurable backoff strategies.
Per-run configuration applied to agent execution.
Streaming result wrapper exposing semantic and raw event streams plus cancellation controls.
Subprocess environment construction (originator override, API key forwarding).
Session-oriented runtime kit for the common Codex exec CLI family.
Deduplicated warn-once logic for keyring-related warnings.
Behaviour for persisting conversation state across runs.
In-memory session adapter backed by an Agent. Suitable for tests and short-lived runs.
Helpers for inspecting Codex CLI session files and replaying recorded changes.
Helpers for discovering and loading Codex skills.
Signals that the agent or run configuration was updated for this stream.
Guardrail evaluation outcome streamed to consumers.
Batch of raw codex events emitted for a turn.
Semantic wrapper for a streamed Codex event.
Tool approval outcome emitted during streaming.
Deterministic host-side helpers for working with subagent threads over app-server.
Telemetry helpers and default logging for Codex events.
Represents a Codex conversation thread and exposes turn execution APIs.
Per-thread configuration options.
Behaviour and helper macros for Codex tool modules.
Guardrail applied before or after tool invocation.
Structured tool output helpers that mirror the Responses input payload shapes.
File content tool output.
Image tool output.
Text tool output.
Public API for registering and invoking Codex tools.
Hosted tool for applying Codex apply_patch edits to files.
Hosted code interpreter tool.
Hosted computer action tool with safety callback.
Hosted tool for searching files by name pattern and content.
Registration handle returned from Codex.Tools.register/2.
Hosted MCP tool wrapper that delegates to Codex.MCP.Client.
Hosted image generation tool.
ETS-backed registry that stores Codex tool definitions, tracks invocation telemetry, and provides lookup/invoke helpers used by the auto-run pipeline.
Hosted tool for executing shell scripts via the user's default shell.
Hosted tool for executing shell commands.
Hosted vector store search tool for searching indexed documents.
Hosted tool for attaching local images to the conversation.
Hosted tool for performing web searches.
Hosted tool for writing to an existing exec session.
Behaviour for Codex transport implementations.
Raised when the codex executable exits unexpectedly.
Result struct returned from turn execution.
Voice pipeline for speech-to-speech AI interactions.
A workflow that wraps a Codex.Agent for voice interactions.
Configuration for voice pipelines.
Settings for speech-to-text models.
Settings for text-to-speech models.
Voice stream event types for the voice pipeline.
Audio data event from the voice pipeline.
Error event from the voice pipeline.
Lifecycle event from the voice pipeline.
Audio input types for voice pipelines.
A single, complete audio input buffer.
A streaming audio input that can be appended to.
Behaviours for speech-to-text and text-to-speech models.
Behaviour for voice model providers.
Behaviour for speech-to-text models.
Behaviour for streaming transcription sessions.
Behaviour for text-to-speech models.
OpenAI voice model provider.
OpenAI speech-to-text model implementation.
Buffered streamed transcription session.
OpenAI text-to-speech model implementation.
Orchestrates STT → Workflow → TTS voice pipelines.
Streamed audio result from a voice pipeline.
A simple workflow that uses a function to process transcriptions.
Behaviour for voice workflows.
Backwards-compatible entry module for the Codex SDK.
Mix Tasks
Summarises harvested Python fixtures and highlights gaps.
Runs the recommended verification steps (compile, format, test).