# `Alloy.Provider.Codex`
[🔗](https://github.com/alloy-ex/alloy/blob/v0.12.4/lib/alloy/provider/codex.ex#L1)

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.

# `config`

```elixir
@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.

---

*Consult [api-reference.md](api-reference.md) for complete listing*