# Codex SDK v0.6.0 - Table of Contents ## Pages - Introduction - [README](readme.md) - [Getting Started](01-getting-started.md) - Guides - [Architecture Guide](02-architecture.md) - [App-server Transport (JSON-RPC over stdio)](05-app-server-transport.md) - Reference - [LICENSE](license.md) - [API Reference](03-api-reference.md) - [Examples and Usage Patterns](04-examples.md) - Changelog - [Changelog](changelog.md) ## Modules - [Codex.Agent](Codex.Agent.md): Defines a reusable agent with instructions, tools, and hooks. - [Codex.AgentRunner](Codex.AgentRunner.md): Multi-turn runner that orchestrates agent execution over Codex threads. - [Codex.AppServer](Codex.AppServer.md): App-server transport for stateful, bidirectional communication with Codex. - [Codex.AppServer.Mcp](Codex.AppServer.Mcp.md): MCP (Model Context Protocol) server management for app-server connections. - [Codex.AppServer.V1](Codex.AppServer.V1.md): Legacy v1 app-server endpoints for compatibility with older servers. - [Codex.Events.AccountLoginCompleted](Codex.Events.AccountLoginCompleted.md): Event emitted when account login completes. - [Codex.Events.AccountRateLimitsUpdated](Codex.Events.AccountRateLimitsUpdated.md): Event emitted when account rate limits are updated. - [Codex.Events.AccountUpdated](Codex.Events.AccountUpdated.md): Event emitted when account authentication state changes. - [Codex.Events.AppServerNotification](Codex.Events.AppServerNotification.md): Lossless wrapper for an app-server notification that is not yet mapped into a typed event. - [Codex.Events.CollabAgentInteractionBegin](Codex.Events.CollabAgentInteractionBegin.md): Collab event emitted when an agent interaction starts. - [Codex.Events.CollabAgentInteractionEnd](Codex.Events.CollabAgentInteractionEnd.md): Collab event emitted when an agent interaction completes. - [Codex.Events.CollabAgentSpawnBegin](Codex.Events.CollabAgentSpawnBegin.md): Collab event emitted when an agent spawn starts. - [Codex.Events.CollabAgentSpawnEnd](Codex.Events.CollabAgentSpawnEnd.md): Collab event emitted when an agent spawn completes. - [Codex.Events.CollabCloseBegin](Codex.Events.CollabCloseBegin.md): Collab event emitted when a collab session begins closing. - [Codex.Events.CollabCloseEnd](Codex.Events.CollabCloseEnd.md): Collab event emitted when a collab session closes. - [Codex.Events.CollabWaitingBegin](Codex.Events.CollabWaitingBegin.md): Collab event emitted when an agent begins waiting. - [Codex.Events.CollabWaitingEnd](Codex.Events.CollabWaitingEnd.md): Collab event emitted when an agent stops waiting. - [Codex.Events.CommandOutputDelta](Codex.Events.CommandOutputDelta.md): Event delta emitted while a command execution is producing output. - [Codex.Events.ConfigWarning](Codex.Events.ConfigWarning.md): Event emitted when configuration warnings are reported. - [Codex.Events.ContextCompacted](Codex.Events.ContextCompacted.md): Indicates that the conversation context was compacted. - [Codex.Events.DeprecationNotice](Codex.Events.DeprecationNotice.md): Event emitted when the server reports a deprecated feature or behavior. - [Codex.Events.ElicitationRequest](Codex.Events.ElicitationRequest.md): Event emitted for MCP elicitation requests. - [Codex.Events.EnteredReviewMode](Codex.Events.EnteredReviewMode.md): Event emitted when a review session starts. - [Codex.Events.Error](Codex.Events.Error.md): General error event emitted by the CLI. - [Codex.Events.ExitedReviewMode](Codex.Events.ExitedReviewMode.md): Event emitted when a review session ends. - [Codex.Events.FileChangeOutputDelta](Codex.Events.FileChangeOutputDelta.md): Event delta emitted while a file change stream is producing output. - [Codex.Events.ItemAgentMessageDelta](Codex.Events.ItemAgentMessageDelta.md): Event delta emitted when the agent produces message content. - [Codex.Events.ItemCompleted](Codex.Events.ItemCompleted.md): Event emitted when an item completes. - [Codex.Events.ItemInputTextDelta](Codex.Events.ItemInputTextDelta.md): Event delta emitted for user input text items. - [Codex.Events.ItemStarted](Codex.Events.ItemStarted.md): Event emitted when an item begins processing. - [Codex.Events.ItemUpdated](Codex.Events.ItemUpdated.md): Event emitted when an in-progress item receives an update. - [Codex.Events.McpServerOauthLoginCompleted](Codex.Events.McpServerOauthLoginCompleted.md): Event emitted when an MCP server OAuth login completes. - [Codex.Events.McpStartupComplete](Codex.Events.McpStartupComplete.md): Summary of MCP server startup completion. - [Codex.Events.McpStartupUpdate](Codex.Events.McpStartupUpdate.md): Incremental status update for MCP server startup. - [Codex.Events.McpToolCallProgress](Codex.Events.McpToolCallProgress.md): Progress message emitted while an MCP tool call is running. - [Codex.Events.RawResponseItemCompleted](Codex.Events.RawResponseItemCompleted.md): Event emitted when a raw response item completes on the app-server stream. - [Codex.Events.ReasoningDelta](Codex.Events.ReasoningDelta.md): Event delta emitted while reasoning content is streaming. - [Codex.Events.ReasoningSummaryDelta](Codex.Events.ReasoningSummaryDelta.md): Event delta emitted while reasoning summary text is streaming. - [Codex.Events.ReasoningSummaryPartAdded](Codex.Events.ReasoningSummaryPartAdded.md): Event emitted when a new reasoning summary part is added. - [Codex.Events.RequestUserInput](Codex.Events.RequestUserInput.md): Event emitted when the agent requests user input. - [Codex.Events.SessionConfigured](Codex.Events.SessionConfigured.md): Event emitted when a session is configured. - [Codex.Events.ShutdownComplete](Codex.Events.ShutdownComplete.md): Event emitted when the agent shuts down. - [Codex.Events.TerminalInteraction](Codex.Events.TerminalInteraction.md): Event emitted when stdin is written to an interactive command execution. - [Codex.Events.ThreadRolledBack](Codex.Events.ThreadRolledBack.md): Indicates that recent user turns were removed from context. - [Codex.Events.ThreadStarted](Codex.Events.ThreadStarted.md): Event emitted when a thread is first created. - [Codex.Events.ThreadTokenUsageUpdated](Codex.Events.ThreadTokenUsageUpdated.md): Incremental token usage update emitted while a turn is in flight. - [Codex.Events.ToolCallCompleted](Codex.Events.ToolCallCompleted.md): Event emitted when a tool call has completed and returned output. - [Codex.Events.ToolCallRequested](Codex.Events.ToolCallRequested.md): Indicates Codex requires a tool invocation to continue auto-run. - [Codex.Events.TurnAborted](Codex.Events.TurnAborted.md): Event emitted when a turn is aborted. - [Codex.Events.TurnCompaction](Codex.Events.TurnCompaction.md): Signals that Codex compacted a turn's history. - [Codex.Events.TurnCompleted](Codex.Events.TurnCompleted.md): Final event for a turn, optionally carrying final response and usage data. - [Codex.Events.TurnContinuation](Codex.Events.TurnContinuation.md): Signals that a continuation token is available for resuming the turn. - [Codex.Events.TurnDiffUpdated](Codex.Events.TurnDiffUpdated.md): Event emitted when the app-server publishes a turn diff update. - [Codex.Events.TurnFailed](Codex.Events.TurnFailed.md): Event emitted when a turn fails. - [Codex.Events.TurnPlanUpdated](Codex.Events.TurnPlanUpdated.md): Event emitted when the app-server publishes an updated plan for the current turn. - [Codex.Events.TurnStarted](Codex.Events.TurnStarted.md): Event emitted when a new turn starts. - [Codex.Events.UndoCompleted](Codex.Events.UndoCompleted.md): Event emitted when an undo operation completes. - [Codex.Events.UndoStarted](Codex.Events.UndoStarted.md): Event emitted when an undo operation begins. - [Codex.Events.Warning](Codex.Events.Warning.md): Warning event emitted during a turn. - [Codex.Events.WindowsWorldWritableWarning](Codex.Events.WindowsWorldWritableWarning.md): Event emitted when world-writable Windows paths are detected. - [Codex.FileSearch](Codex.FileSearch.md): Configuration for file search capabilities in threads and runs. - [Codex.Files.Attachment](Codex.Files.Attachment.md): Represents a staged file attachment. - [Codex.FunctionTool](Codex.FunctionTool.md): Convenience macro for defining function-backed tools with JSON schemas. - [Codex.Guardrail](Codex.Guardrail.md): Represents an input or output guardrail invoked around agent execution. - [Codex.HTTPClient](Codex.HTTPClient.md): HTTP client abstraction for making HTTP requests. - [Codex.HTTPClient.Mock](Codex.HTTPClient.Mock.md): Mock HTTP client for testing. - [Codex.HTTPClient.Req](Codex.HTTPClient.Req.md): HTTP client implementation using Req. - [Codex.Handoff](Codex.Handoff.md): Represents a handoff from one agent to another, wrapping the downstream agent as a tool with optional input filtering and history nesting controls. - [Codex.Handoff.InputData](Codex.Handoff.InputData.md): Carries conversation history and run context into handoff input filters. - [Codex.Items.AgentMessage](Codex.Items.AgentMessage.md): Assistant-authored message item emitted by the Codex runtime, with optional parsed payloads for structured output experiments. - [Codex.Items.CommandExecution](Codex.Items.CommandExecution.md): Captures an execution request made by the agent, including aggregated output and status metadata. - [Codex.Items.Compaction](Codex.Items.Compaction.md): Raw response item emitted when compaction summaries are generated. - [Codex.Items.Error](Codex.Items.Error.md): Normalised error record describing failures surfaced during a turn. - [Codex.Items.FileChange](Codex.Items.FileChange.md): Represents a file diff emitted by the agent, including per-path change metadata and completion status. - [Codex.Items.GhostSnapshot](Codex.Items.GhostSnapshot.md): Raw response item describing a ghost snapshot captured for undo. - [Codex.Items.ImageView](Codex.Items.ImageView.md): An image view event emitted by the app-server when it renders a local image. - [Codex.Items.McpToolCall](Codex.Items.McpToolCall.md): Metadata describing a tool invocation routed through an MCP server. - [Codex.Items.RawResponseItem](Codex.Items.RawResponseItem.md): Fallback container for unparsed raw response items. - [Codex.Items.Reasoning](Codex.Items.Reasoning.md): Intermediate reasoning trace shared as part of tool or agent transparency. - [Codex.Items.ReviewMode](Codex.Items.ReviewMode.md): Indicates that review mode has been entered or exited. - [Codex.Items.TodoList](Codex.Items.TodoList.md): Structured checklist shared by the agent to track outstanding follow-up items. - [Codex.Items.UserMessage](Codex.Items.UserMessage.md): User-authored message item carrying a list of input blocks. - [Codex.Items.WebSearch](Codex.Items.WebSearch.md): Records a web search request issued by the agent, preserving the original query. - [Codex.ModelSettings](Codex.ModelSettings.md): Model tuning options and provider selection used to configure codex runs. - [Codex.Models](Codex.Models.md): Known Codex models and their defaults. - [Codex.Protocol.ByteRange](Codex.Protocol.ByteRange.md): Byte range for text element positioning. - [Codex.Protocol.CollaborationMode](Codex.Protocol.CollaborationMode.md): Collaboration mode configuration with presets. - [Codex.Protocol.ConfigTypes](Codex.Protocol.ConfigTypes.md): Protocol configuration type enums and converters. - [Codex.Protocol.Elicitation](Codex.Protocol.Elicitation.md): MCP elicitation request and action types. - [Codex.Protocol.Elicitation.Request](Codex.Protocol.Elicitation.Request.md): MCP elicitation request - [Codex.Protocol.Ops](Codex.Protocol.Ops.md): Encoders for Codex protocol operations submitted to the runtime. - [Codex.Protocol.RateLimit](Codex.Protocol.RateLimit.md): Rate limit snapshot types for TokenCount events. - [Codex.Protocol.RateLimit.CreditsSnapshot](Codex.Protocol.RateLimit.CreditsSnapshot.md): Credits balance snapshot - [Codex.Protocol.RateLimit.Snapshot](Codex.Protocol.RateLimit.Snapshot.md): Complete rate limit snapshot - [Codex.Protocol.RateLimit.Window](Codex.Protocol.RateLimit.Window.md): A rate limit window - [Codex.Protocol.RequestUserInput](Codex.Protocol.RequestUserInput.md): Types for agent-to-user input requests. - [Codex.Protocol.RequestUserInput.Answer](Codex.Protocol.RequestUserInput.Answer.md): An answer to a question - [Codex.Protocol.RequestUserInput.Option](Codex.Protocol.RequestUserInput.Option.md): An option for a question - [Codex.Protocol.RequestUserInput.Question](Codex.Protocol.RequestUserInput.Question.md): A question to present to the user - [Codex.Protocol.RequestUserInput.Response](Codex.Protocol.RequestUserInput.Response.md): Response containing answers to all questions - [Codex.Protocol.TextElement](Codex.Protocol.TextElement.md): Text element with byte range for rich text input. - [Codex.RateLimit](Codex.RateLimit.md): Rate limit detection and handling utilities. - [Codex.Realtime](Codex.Realtime.md): Placeholder for realtime pipelines. - [Codex.Retry](Codex.Retry.md): Retry logic with configurable backoff strategies. - [Codex.RunConfig](Codex.RunConfig.md): Per-run configuration applied to agent execution. - [Codex.RunResultStreaming](Codex.RunResultStreaming.md): Streaming result wrapper exposing semantic and raw event streams plus cancellation controls. - [Codex.Session](Codex.Session.md): Behaviour for persisting conversation state across runs. - [Codex.Session.Memory](Codex.Session.Memory.md): In-memory session adapter backed by an Agent. Suitable for tests and short-lived runs. - [Codex.Sessions](Codex.Sessions.md): Helpers for inspecting Codex CLI session files and replaying recorded changes. - [Codex.StreamEvent.AgentUpdated](Codex.StreamEvent.AgentUpdated.md): Signals that the agent or run configuration was updated for this stream. - [Codex.StreamEvent.GuardrailResult](Codex.StreamEvent.GuardrailResult.md): Guardrail evaluation outcome streamed to consumers. - [Codex.StreamEvent.RawResponses](Codex.StreamEvent.RawResponses.md): Batch of raw codex events emitted for a turn. - [Codex.StreamEvent.RunItem](Codex.StreamEvent.RunItem.md): Semantic wrapper for a streamed Codex event. - [Codex.StreamEvent.ToolApproval](Codex.StreamEvent.ToolApproval.md): Tool approval outcome emitted during streaming. - [Codex.ToolGuardrail](Codex.ToolGuardrail.md): Guardrail applied before or after tool invocation. - [Codex.ToolOutput](Codex.ToolOutput.md): Structured tool output helpers that mirror the Responses input payload shapes. - [Codex.ToolOutput.FileContent](Codex.ToolOutput.FileContent.md): File content tool output. - [Codex.ToolOutput.Image](Codex.ToolOutput.Image.md): Image tool output. - [Codex.ToolOutput.Text](Codex.ToolOutput.Text.md): Text tool output. - [Codex.Tools.ApplyPatchTool](Codex.Tools.ApplyPatchTool.md): Hosted tool for applying Codex apply_patch edits to files. - [Codex.Tools.CodeInterpreterTool](Codex.Tools.CodeInterpreterTool.md): Hosted code interpreter tool. - [Codex.Tools.ComputerTool](Codex.Tools.ComputerTool.md): Hosted computer action tool with safety callback. - [Codex.Tools.FileSearchTool](Codex.Tools.FileSearchTool.md): Hosted tool for searching files by name pattern and content. - [Codex.Tools.Handle](Codex.Tools.Handle.md): Registration handle returned from `Codex.Tools.register/2`. - [Codex.Tools.HostedMcpTool](Codex.Tools.HostedMcpTool.md): Hosted MCP tool wrapper that delegates to `Codex.MCP.Client`. - [Codex.Tools.ImageGenerationTool](Codex.Tools.ImageGenerationTool.md): Hosted image generation tool. - [Codex.Tools.ShellCommandTool](Codex.Tools.ShellCommandTool.md): Hosted tool for executing shell scripts via the user's default shell. - [Codex.Tools.ShellTool](Codex.Tools.ShellTool.md): Hosted tool for executing shell commands. - [Codex.Tools.VectorStoreSearchTool](Codex.Tools.VectorStoreSearchTool.md): Hosted vector store search tool for searching indexed documents. - [Codex.Tools.ViewImageTool](Codex.Tools.ViewImageTool.md): Hosted tool for attaching local images to the conversation. - [Codex.Tools.WebSearchTool](Codex.Tools.WebSearchTool.md): Hosted tool for performing web searches. - [Codex.Tools.WriteStdinTool](Codex.Tools.WriteStdinTool.md): Hosted tool for writing to an existing exec session. - [Codex.Transport](Codex.Transport.md): Behaviour for Codex transport implementations. - [Codex.Voice](Codex.Voice.md): Placeholder for voice pipelines. - [CodexSdk](CodexSdk.md): Backwards-compatible entry module for the Codex SDK. - Public API - [Codex](Codex.md): Public entry point for the Codex SDK. - [Codex.Options](Codex.Options.md): Global configuration for Codex interactions. - [Codex.Thread](Codex.Thread.md): Represents a Codex conversation thread and exposes turn execution APIs. - [Codex.Thread.Options](Codex.Thread.Options.md): Per-thread configuration options. - [Codex.Turn.Result](Codex.Turn.Result.md): Result struct returned from turn execution. - Execution - [Codex.Events](Codex.Events.md): Typed event structs emitted during Codex turn execution. - [Codex.Exec](Codex.Exec.md): Process manager wrapping the `codex` binary via erlexec. - [Codex.Items](Codex.Items.md): Typed representations of thread items emitted by the Codex runtime. - [Codex.Telemetry](Codex.Telemetry.md): Telemetry helpers and default logging for Codex events. - Files - [Codex.Files](Codex.Files.md): Attachment staging helpers mirroring the Python SDK file APIs. - [Codex.Files.Registry](Codex.Files.Registry.md): 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. - [Codex.OutputSchemaFile](Codex.OutputSchemaFile.md): 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. - Approvals - [Codex.ApprovalError](Codex.ApprovalError.md): Error returned when an approval policy denies a tool invocation. - [Codex.Approvals](Codex.Approvals.md): Approval helpers invoked by the auto-run pipeline when actions require consent. - [Codex.Approvals.Hook](Codex.Approvals.Hook.md): Behaviour for implementing pluggable approval hooks. - [Codex.Approvals.Registry](Codex.Approvals.Registry.md): ETS-based registry for tracking async approval requests. - [Codex.Approvals.StaticPolicy](Codex.Approvals.StaticPolicy.md): Simple allow/deny approval policy used for tests and defaults. - Tooling - [Codex.MCP.Client](Codex.MCP.Client.md): MCP JSON-RPC client for stdio and streamable HTTP transports. - [Codex.MCP.Config](Codex.MCP.Config.md): Helpers for managing MCP server configuration through app-server config APIs. - [Codex.MCP.OAuth](Codex.MCP.OAuth.md): Stores and refreshes OAuth credentials for streamable HTTP MCP servers. - [Codex.MCP.Transport.Stdio](Codex.MCP.Transport.Stdio.md): Runs MCP servers over stdio using a managed subprocess. - [Codex.MCP.Transport.StreamableHTTP](Codex.MCP.Transport.StreamableHTTP.md): Implements MCP JSON-RPC over HTTP with optional bearer or OAuth auth. - [Codex.Prompts](Codex.Prompts.md): Custom prompt discovery and expansion helpers. - [Codex.Skills](Codex.Skills.md): Helpers for discovering and loading Codex skills. - [Codex.Tool](Codex.Tool.md): Behaviour and helper macros for Codex tool modules. - [Codex.Tools](Codex.Tools.md): Public API for registering and invoking Codex tools. - [Codex.Tools.Registry](Codex.Tools.Registry.md): ETS-backed registry that stores Codex tool definitions, tracks invocation telemetry, and provides lookup/invoke helpers used by the auto-run pipeline. - Errors - [Codex.Error](Codex.Error.md): Base error struct for Codex failures. - [Codex.TransportError](Codex.TransportError.md): Raised when the codex executable exits unexpectedly. - Exceptions - [Codex.GuardrailError](Codex.GuardrailError.md): Error raised when a guardrail rejects or trips during execution. ## Mix Tasks - Tasks - [mix codex.parity](Mix.Tasks.Codex.Parity.md): Summarises harvested Python fixtures and highlights gaps. - [mix codex.verify](Mix.Tasks.Codex.Verify.md): Runs the recommended verification steps (compile, format, test).