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 (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)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
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".
Source Files