codex

Documentation

Overview

Package codex provides a Codex CLI backend for agentrun.

This backend implements cli.Spawner, cli.Parser, and cli.Resumer to drive Codex as a subprocess, translating its nd-JSON output into agentrun.Message values. It does NOT implement cli.Streamer or cli.InputFormatter — Codex uses resume-per-turn for multi-turn conversation.

Resume-per-turn pattern

Codex's exec command is single-shot: provide a message, get a response, process exits. For multi-turn, each Send() spawns a new process via "codex exec resume --json <thread_id> <prompt>". The thread ID is auto-captured from the first thread.started event and stored in the Backend (one instance per session).

Callers relying on auto-capture must wait for MessageInit before calling Send, or supply OptionResumeID upfront.

Supported options

Cross-cutting (root package):

• Session.Model → -m <model>
• OptionMode → sandbox policy (ModePlan → --sandbox read-only on exec)
• OptionHITL → automation (HITLOff → --full-auto, suppressed by ModePlan)
• OptionResumeID → thread ID for exec resume (auto-captured or explicit). Consumers capture the thread ID from MessageInit.ResumeID. Accepts UUID or thread name (codex resolves both).

Backend-specific (namespaced with "codex." prefix):

• OptionSandbox → --sandbox (exec only, not resume)
• OptionEphemeral → --ephemeral
• OptionProfile → -p <profile> (exec only)
• OptionOutputSchema → --output-schema <file> (exec only)
• OptionSkipGitCheck → --skip-git-repo-check

Flag support: exec vs exec resume

Exec only (first turn): --sandbox, -p, --output-schema Both exec and resume: -m, --full-auto, --ephemeral, --skip-git-repo-check, --json

The sandbox policy established on the first exec persists for the session. ModePlan on resume suppresses --full-auto but does not emit --sandbox (not supported by the CLI on resume).

Event types

Codex exec emits JSONL events with a top-level "type" field: thread.started, turn.started, item.started, item.completed, turn.completed, turn.failed, error.

item.completed contains a nested "item" object with its own "type": agent_message, reasoning, command_execution, error, file_changes, web_search, mcp_tool_call.

Unlike Claude, Codex emits complete blocks (no streaming deltas) and events lack a timestamp field (engine auto-sets via time.Now).

Minimum tested version

codex-cli v0.105.0 (exec --json format).

Index

• Constants
• type Backend
  • func New(opts ...Option) *Backend
  • func (b *Backend) ParseLine(line string) (agentrun.Message, error)
  • func (b *Backend) ResumeArgs(session agentrun.Session, initialPrompt string) (string, []string, error)
  • func (b *Backend) SpawnArgs(session agentrun.Session) (string, []string)
  • func (b *Backend) ThreadID() string
• type Option
  • func WithBinary(path string) Option
• type Sandbox

Constants

const (
	// OptionSandbox sets the --sandbox flag for codex exec.
	// Values should be Sandbox constants (SandboxReadOnly, etc.).
	// First turn only — not available on exec resume.
	// Ignored when root OptionMode or OptionHITL is set (independent surfaces).
	OptionSandbox = "codex.sandbox"

	// OptionEphemeral enables --ephemeral mode (no session persistence).
	// Any non-empty value adds the flag.
	OptionEphemeral = "codex.ephemeral"

	// OptionProfile sets the -p <profile> flag for codex exec.
	// First turn only — not available on exec resume.
	OptionProfile = "codex.profile"

	// OptionOutputSchema sets the --output-schema <file> flag.
	// First turn only — not available on exec resume.
	OptionOutputSchema = "codex.output_schema"

	// OptionSkipGitCheck adds --skip-git-repo-check.
	// Any non-empty value adds the flag.
	OptionSkipGitCheck = "codex.skip_git_check"
)

Session option keys specific to the Codex backend. Namespaced with "codex." to prevent collision across backends. Cross-cutting options (OptionMode, OptionHITL, OptionResumeID) are defined in the root agentrun package.

Types

type Backend

type Backend struct {
	// contains filtered or unexported fields
}

Backend is a Codex CLI backend for agentrun. It implements cli.Spawner, cli.Parser, and cli.Resumer.

Codex does NOT support streaming input (no cli.Streamer or cli.InputFormatter). Multi-turn conversation uses resume-per-turn: each Send() spawns a new subprocess via "codex exec resume".

One Backend instance per session. The thread ID is auto-captured from the first thread.started event via atomic write-once.

func New

func New(opts ...Option) *Backend

New creates a Codex CLI backend with the given options. The default binary is "codex".

func (*Backend) ParseLine

func (b *Backend) ParseLine(line string) (agentrun.Message, error)

ParseLine parses a single JSONL output line from codex exec into a Message. Returns cli.ErrSkipLine for blank lines and no-op events (turn.started, item.started).

func (*Backend) ResumeArgs

func (b *Backend) ResumeArgs(session agentrun.Session, initialPrompt string) (string, []string, error)

ResumeArgs builds exec.Cmd arguments to resume an existing Codex session. The thread ID is resolved from:

1. The atomic write-once ID captured from thread.started (auto-capture)
2. session.Options[OptionResumeID] (explicit fallback)

Returns an error if no thread ID is available, if the prompt contains null bytes, or if session options are invalid.

func (*Backend) SpawnArgs

func (b *Backend) SpawnArgs(session agentrun.Session) (string, []string)

SpawnArgs builds exec.Cmd arguments for a new Codex session. When OptionResumeID is set, produces "exec resume" subcommand. Invalid option values are silently skipped per the Spawner contract.

func (*Backend) ThreadID

func (b *Backend) ThreadID() string

ThreadID returns the auto-captured thread ID, or empty string if not yet captured or if only a non-UUID sentinel was stored.

type Option

type Option func(*Backend)

Option configures a Backend at construction time.

func WithBinary

func WithBinary(path string) Option

WithBinary overrides the Codex CLI binary path. Empty values are ignored; the default is "codex".

type Sandbox

type Sandbox string

Sandbox controls the sandbox policy via --sandbox.

const (
	SandboxReadOnly       Sandbox = "read-only"
	SandboxWorkspaceWrite Sandbox = "workspace-write"
	SandboxFullAccess     Sandbox = "danger-full-access"
)