Alloy.Provider.Codex (alloy v0.12.4)

Provider for ChatGPT-plan-backed Codex execution via codex exec.

This provider treats Codex as a structured completion backend rather than a full agent runtime. Alloy remains responsible for the tool loop, while Codex receives the current transcript and available tool definitions, then returns JSON describing either a final assistant response or one or more tool calls.

Config

Required:

:model - Codex model name (for example "gpt-5.4")

Optional:

:codex_bin - Executable path (default: "codex")
:workdir - Directory passed to codex exec (defaults to a temp dir)
:profile - Optional Codex config profile
:codex_home - Override CODEX_HOME instead of creating an isolated temp home
:auth_path - Override source auth.json copied into the isolated home (default: ~/.codex/auth.json)
:tmp_dir - Parent for the provider's temp working directory (default: System.tmp_dir!/0)
:timeout_ms - Timeout for a single codex exec invocation (default: 120_000)
:receive_timeout - Optional turn deadline timeout injected by Alloy's retry loop; when present it caps :timeout_ms
:command_runner - Test hook matching System.cmd/3
:system_prompt - System prompt string

Notes

Authentication is handled by the local codex CLI login state.
By default the provider creates a minimal temporary CODEX_HOME containing only auth.json, which avoids pulling in the user's full MCP/plugin config.
Usage accounting is not exposed by codex exec in a structured form yet, so this provider currently reports zero token counts.
Streaming is emulated by running a normal completion and replaying the final text to the provided callback.

Summary

Types

config()

Configuration for the Codex provider. See the module doc for field semantics.

Types

config()

@type config() :: %{
  :model => String.t(),
  optional(:codex_bin) => String.t(),
  optional(:workdir) => String.t(),
  optional(:profile) => String.t(),
  optional(:codex_home) => String.t(),
  optional(:auth_path) => String.t(),
  optional(:tmp_dir) => String.t(),
  optional(:timeout_ms) => pos_integer(),
  optional(:receive_timeout) => pos_integer(),
  optional(:system_prompt) => String.t(),
  optional(:command_runner) => (String.t(), [String.t()], keyword() ->
                                  {String.t(), integer()})
}

Configuration for the Codex provider. See the module doc for field semantics.