codex

Documentation

Overview

Package codex implements the agent.Agent interface by shelling out to OpenAI's Codex CLI (`codex` / `@openai/codex`). It reuses the shared prompt templates and helpers from internal/agent/prompt so its planning and review prompts are identical to the claude and opencode providers.

Key differences from the other providers:

• The headless mode is the `codex exec` subcommand (the interactive TUI used by Discuss is `codex` with no subcommand).
• Structured output for Plan and Review is native: an embedded JSON Schema is materialized to a temp file and passed via --output-schema, and the final agent message is written to a file via --output-last-message.
• Auth: Codex reads CODEX_API_KEY (highest precedence). OPENAI_API_KEY is NOT in Codex's main auth path, so childEnv() maps it into CODEX_API_KEY for the child process when CODEX_API_KEY is unset.

Index

• type CodexAgent
  • func NewAgent(binaryPath, model, reasoningEffort string) *CodexAgent
  • func (c *CodexAgent) Discuss(ctx context.Context, opts agent.DiscussOptions) error
  • func (c *CodexAgent) Execute(ctx context.Context, task agent.TaskSpec, opts agent.ExecOptions) (*agent.ExecResult, error)
  • func (c *CodexAgent) Plan(ctx context.Context, initialPrompt string, opts agent.PlanOptions) (*agent.Plan, error)
  • func (c *CodexAgent) Review(ctx context.Context, diff string, opts agent.ReviewOptions) (*agent.ReviewResult, error)

Types

type CodexAgent

type CodexAgent struct {
	BinaryPath      string // path to `codex` CLI (default: "codex")
	Model           string // bare model ID, e.g. "gpt-5-codex" (optional)
	ReasoningEffort string // "minimal"|"low"|"medium"|"high" (default: "medium")
}

CodexAgent implements agent.Agent using the Codex CLI.

func NewAgent

func NewAgent(binaryPath, model, reasoningEffort string) *CodexAgent

NewAgent creates a new CodexAgent with the given binary path, model, and reasoning effort. If binaryPath is empty, defaults to "codex". If reasoningEffort is empty, defaults to "medium".

func (*CodexAgent) Discuss

func (c *CodexAgent) Discuss(ctx context.Context, opts agent.DiscussOptions) error

Discuss launches the Codex interactive TUI (`codex` with no subcommand) with stdio wired through to the user. Codex's TUI has no system-prompt or initial-prompt flag in scope, so there is no clean way to seed the rendered system/initial prompt; this implementation passes stdio through directly and does no output parsing. The system prompt is still required at the API level for parity with the other providers.

func (*CodexAgent) Execute

func (c *CodexAgent) Execute(ctx context.Context, task agent.TaskSpec, opts agent.ExecOptions) (*agent.ExecResult, error)

Execute runs Codex in headless mode (`codex exec`) to complete a task. The task body (or opts.SystemPrompt, if set) is passed as the positional prompt. The final agent message is captured via --output-last-message and returned in ExecResult.Summary; the agent commits as it works in the repo.

If the final message looks suspicious (empty, "Execution error", or very short), Execute retries once after prompt.RetryDelay before returning an error.

Note: Codex has no --max-turns flag; opts.MaxTurns is ignored for this provider (mirroring opencode).

func (*CodexAgent) Plan

func (c *CodexAgent) Plan(ctx context.Context, initialPrompt string, opts agent.PlanOptions) (*agent.Plan, error)

Plan runs Codex to produce a structured plan. Unlike the claude and opencode providers (which drive an interactive TUI), the Codex Plan uses the headless `codex exec` mode with native structured output: an embedded JSON Schema is passed via --output-schema and the final JSON message is written via --output-last-message, then parsed with prompt.ReadPlanFile.

The rendered planning system prompt and the optional initialPrompt are folded together into the positional prompt (Codex exec has no --system-prompt flag).

func (*CodexAgent) Review

func (c *CodexAgent) Review(ctx context.Context, diff string, opts agent.ReviewOptions) (*agent.ReviewResult, error)

Review runs Codex in headless mode (`codex exec`) to review a diff using native structured output. Because Codex exec has no --system-prompt flag, the review system prompt is folded into the positional message (like opencode). An embedded JSON Schema is passed via --output-schema and the final JSON message is written via --output-last-message.

Returns a structured review result parsed from the agent's JSON output; unparseable output yields ReviewResult{Approved:false, IsUnparseable:true} with a Summary beginning "Failed to parse".