Provider adapter for Codex (Claude Code CLI) integration.
This adapter implements the ProviderAdapter behaviour and provides:
- Streaming execution via Codex SDK's Thread.run_streamed/3
- Tool use support with proper event mapping
- Interrupt/cancel capability
- Accurate capability advertisement
Event Mapping
Codex SDK events are mapped to normalized events as follows:
| Codex Event | Normalized Event | Notes |
|---|---|---|
| ThreadStarted | run_started | Signals execution has begun |
| ItemAgentMessageDelta | message_streamed | Each delta emits a stream event |
| ThreadTokenUsageUpdated | token_usage_updated | Usage statistics |
| ItemStarted (tool items) | tool_call_started | Command/file/MCP tool start |
| ItemCompleted (tool items) | tool_call_completed | Command/file/MCP tool completion |
| ToolCallRequested | tool_call_started | Tool invocation requested |
| ToolCallCompleted | tool_call_completed | Tool finished with output |
| TurnCompleted | message_received, | Emits full message then completion |
| run_completed | ||
| Error / TurnFailed | error_occurred, | Error handling |
| run_failed |
Usage
{:ok, adapter} = CodexAdapter.start_link(working_directory: "/path/to/project")
{:ok, capabilities} = CodexAdapter.capabilities(adapter)
{:ok, session} = Session.new(%{agent_id: "my-agent"})
{:ok, run} = Run.new(%{session_id: session.id, input: "Hello"})
{:ok, result} = CodexAdapter.execute(adapter, run, session,
event_callback: fn event -> IO.inspect(event) end
)Configuration
Required:
:working_directory- Working directory for Codex operations
Optional:
:model- Model to use (default: determined by Codex):sdk_module- SDK module for testing (default: real Codex SDK):sdk_pid- SDK process for testing
Summary
Functions
Returns a specification to start this module under a supervisor.
Starts the Codex adapter.
Stops the adapter.
Functions
Returns a specification to start this module under a supervisor.
See Supervisor.
@spec start_link(keyword()) :: GenServer.on_start()
Starts the Codex adapter.
Options
:working_directory- Required. The working directory for Codex operations.:model- Optional. The model to use.:permission_mode- Optional. Normalized permission mode (seeAgentSessionManager.PermissionMode).:sdk_module- Optional. Mock SDK module for testing.:sdk_pid- Optional. Mock SDK process for testing.:name- Optional. GenServer name for registration.
@spec stop(GenServer.server()) :: :ok
Stops the adapter.