CodexWrapper (CodexWrapper v0.4.0)

Elixir wrapper for the Codex CLI.

Provides a typed interface for executing commands against the codex CLI.

Quick start

# Simple one-shot exec
{:ok, result} = CodexWrapper.exec("fix the failing test", working_dir: "/path/to/project")

# Full control via Exec builder
config = CodexWrapper.Config.new(working_dir: "/path/to/project")

CodexWrapper.Exec.new("implement the feature")
|> CodexWrapper.Exec.model("o3")
|> CodexWrapper.Exec.sandbox(:danger_full_access)
|> CodexWrapper.Exec.execute(config)

Binary discovery

The codex binary is found via (in order):

:binary option passed directly
CODEX_CLI environment variable
System PATH lookup

Summary

Functions

completion(shell \\ :bash, opts \\ [])

Generate a shell completion script.

exec(prompt, opts \\ [])

Execute a prompt non-interactively and return the result.

exec_json(prompt, opts \\ [])

Execute a prompt with --json and return parsed NDJSON events.

raw(args, opts \\ [])

Run an arbitrary CLI command that isn't wrapped by a dedicated module.

review(opts \\ [])

Run a code review via codex exec review.

stream(prompt, opts \\ [])

Execute a prompt and return a lazy stream of %JsonLineEvent{}.

version(opts \\ [])

Get the Codex CLI version.

Functions

completion(shell \\ :bash, opts \\ [])

@spec completion(
  CodexWrapper.Commands.Completion.shell(),
  keyword()
) :: {:ok, String.t()} | {:error, term()}

Generate a shell completion script.

Examples

{:ok, script} = CodexWrapper.completion(:zsh)

exec(prompt, opts \\ [])

@spec exec(
  String.t(),
  keyword()
) :: {:ok, CodexWrapper.Result.t()} | {:error, term()}

Execute a prompt non-interactively and return the result.

Convenience wrapper that builds a Config and Exec from keyword options. Returns {:ok, %Result{}} on success or {:error, reason} on failure.

Options

Config options (passed to CodexWrapper.Config.new/1):

:binary - Path to codex binary
:working_dir - Working directory
:env - Environment variables
:timeout - Timeout in ms
:verbose - Enable verbose output

Exec options (passed to Exec builder):

:model - Model name
:profile - Named config profile (--profile)
:sandbox - Sandbox mode atom
:approval_policy - Approval policy atom (:untrusted, :on_request, :never)
:full_auto - Deprecated; emits --sandbox workspace-write (boolean)
:dangerously_bypass_approvals_and_sandbox - Bypass all (boolean)
:cd - Working directory for codex subprocess
:skip_git_repo_check - Skip git check (boolean)
:search - Web search: true (live), false, or a mode atom (:cached, :indexed, :live, :disabled)
:ephemeral - Ephemeral mode (boolean)
:json - JSON output (boolean)
:output_schema - Output schema path
:output_last_message - Output last message path

Examples

CodexWrapper.exec("fix the tests")
CodexWrapper.exec("implement the feature", working_dir: "/path/to/repo", model: "o3")

exec_json(prompt, opts \\ [])

@spec exec_json(
  String.t(),
  keyword()
) :: {:ok, [CodexWrapper.JsonLineEvent.t()]} | {:error, term()}

Execute a prompt with --json and return parsed NDJSON events.

See exec/2 for available options.

Examples

{:ok, events} = CodexWrapper.exec_json("fix the tests")

raw(args, opts \\ [])

@spec raw(
  [String.t()],
  keyword()
) :: {:ok, String.t()} | {:error, term()}

Run an arbitrary CLI command that isn't wrapped by a dedicated module.

This is the escape hatch for new or experimental CLI subcommands.

Examples

CodexWrapper.raw(["version"])
CodexWrapper.raw(["exec", "fix the tests"], working_dir: "/tmp")

review(opts \\ [])

@spec review(keyword()) :: {:ok, CodexWrapper.Result.t()} | {:error, term()}

Run a code review via codex exec review.

Convenience wrapper that builds a Config and Review from keyword options. Returns {:ok, %Result{}} on success or {:error, reason} on failure.

Options

Config options (passed to CodexWrapper.Config.new/1):

:binary - Path to codex binary
:working_dir - Working directory
:env - Environment variables
:timeout - Timeout in ms
:verbose - Enable verbose output

Review options (passed to Review builder):

:prompt - Additional review context
:uncommitted - Review uncommitted changes (boolean)
:base - Compare against base branch
:commit - Review a specific commit
:title - PR/review title
:model - Model name
:full_auto - Deprecated; emits --sandbox workspace-write (boolean)
:dangerously_bypass_approvals_and_sandbox - Bypass all (boolean)
:skip_git_repo_check - Skip git check (boolean)
:ephemeral - Ephemeral mode (boolean)
:output_schema - Output schema path
:json - JSON output (boolean)
:output_last_message - Output last message path

Examples

CodexWrapper.review(uncommitted: true, working_dir: "/path/to/repo")
CodexWrapper.review(base: "main", model: "o3")

stream(prompt, opts \\ [])

@spec stream(
  String.t(),
  keyword()
) :: Enumerable.t()

Execute a prompt and return a lazy stream of %JsonLineEvent{}.

See exec/2 for available options.

Examples

CodexWrapper.stream("fix the tests")
|> Enum.each(fn event -> IO.inspect(event.event_type) end)

version(opts \\ [])

@spec version(keyword()) ::
  {:ok, %{version: String.t(), raw: String.t()}} | {:error, term()}

Get the Codex CLI version.

Examples

{:ok, %{version: "codex 0.1.0", raw: "codex 0.1.0"}} = CodexWrapper.version()