Codex.CLI.Session (Codex SDK v0.16.1)

Copy Markdown View Source

Raw codex CLI subprocess session backed by CliSubprocessCore.Channel.

One-shot non-PTY command wrappers should use Codex.CLI.run/2, which executes through the shared CliSubprocessCore.Command lane.

Sessions are useful for interactive or long-running commands such as:

  • codex
  • codex resume
  • codex fork
  • codex app-server
  • codex mcp-server

The caller process continues to receive the historical mailbox events:

  • {:stdout, os_pid, binary}
  • {:stderr, os_pid, binary}
  • {:DOWN, os_pid, :process, pid, reason}

Use collect/2 to accumulate output until the process exits.

Summary

Types

result()
t()

Functions

close_input(session)

Closes the subprocess stdin by sending EOF.

collect(session, timeout_ms \\ Defaults.exec_timeout_ms())

Collects stdout/stderr until the subprocess exits.

interrupt(session)

Interrupts the subprocess.

send_input(session, data)

Sends input bytes to the subprocess stdin.

start(binary_or_spec, args, opts \\ [])

Starts a raw subprocess session for a resolved Codex program and args.

stop(session)

Stops the subprocess.

Types

result()

@type result() :: %{
  command: [String.t()],
  args: [String.t()],
  stdout: String.t(),
  stderr: String.t(),
  exit_code: integer(),
  success: boolean()
}

t()

@type t() :: %Codex.CLI.Session{
  args: [String.t()],
  channel: CliSubprocessCore.Channel.t(),
  command: [String.t()],
  os_pid: non_neg_integer(),
  pid: pid(),
  pty?: boolean(),
  receiver: pid(),
  stdin?: boolean()
}

Functions

close_input(session)

@spec close_input(t()) :: :ok | {:error, term()}

Closes the subprocess stdin by sending EOF.

collect(session, timeout_ms \\ Defaults.exec_timeout_ms())

@spec collect(t(), timeout()) :: {:ok, result()} | {:error, term()}

Collects stdout/stderr until the subprocess exits.

interrupt(session)

@spec interrupt(t()) :: :ok | {:error, term()}

Interrupts the subprocess.

send_input(session, data)

@spec send_input(t(), iodata()) :: :ok | {:error, term()}

Sends input bytes to the subprocess stdin.

start(binary_or_spec, args, opts \\ [])

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

Starts a raw subprocess session for a resolved Codex program and args.

stop(session)

@spec stop(t()) :: :ok

Stops the subprocess.