Codex Agent

The Codex agent plugin integrates with OpenAI's codex CLI to execute AI coding tasks. It supports full-auto mode for autonomous operation and configurable sandbox modes for security.

INFO

Codex supports subagent tracing via JSONL output - Ralph TUI can show tool calls in real-time as Codex works.

Prerequisites

Install Codex CLI:

Bash

npm install -g @openai/codex

Verify installation:

Bash

codex --version

Basic Usage

Run with Codex

Use the --agent codex flag:

Bash

ralph-tui run --prd ./prd.json --agent codex

Select a Model

Override the model with --model:

Bash

ralph-tui run --prd ./prd.json --agent codex --model gpt-4

Configure Sandbox Mode

Set sandbox restrictions in config:

TOML

[agentOptions]
sandbox = "workspace-write"

Configuration

Shorthand Config

The simplest configuration:

TOML

# .ralph-tui/config.toml
agent = "codex"
 
[agentOptions]
model = "gpt-4"

Full Config

For advanced control:

TOML

[[agents]]
name = "my-codex"
plugin = "codex"
default = true
command = "codex"
timeout = 300000
 
[agents.options]
model = "gpt-4"
fullAuto = true
sandbox = "workspace-write"

Options Reference

Option	Type	Default	Description
`model`	string	-	OpenAI model to use (e.g., `gpt-4`, `gpt-4-turbo`)
`fullAuto`	boolean	`true`	Enable full-auto mode for autonomous operation
`sandbox`	string	`"workspace-write"`	Sandbox mode for file access restrictions
`timeout`	number	`0`	Execution timeout in ms (0 = no timeout)
`command`	string	`"codex"`	Path to Codex CLI executable

Sandbox Modes

Codex supports three sandbox levels for security:

Mode	Description	Use Case
`read-only`	No file modifications allowed	Safe exploration, code review
`workspace-write`	Can modify workspace files only	Normal development (default)
`danger-full-access`	Full system access	Trusted operations only

Configure via CLI or config:

Bash

# CLI (via agentOptions)
ralph-tui run --prd ./prd.json --agent codex
 
# Config
[agentOptions]
sandbox = "workspace-write"

INFO

Use danger-full-access only when absolutely necessary. It grants Codex full system access without restrictions.

Full-Auto Mode

When fullAuto is enabled (default), Codex will auto-approve all actions without prompting. This is required for Ralph TUI's autonomous operation since it cannot relay interactive prompts.

TOML

[agentOptions]
fullAuto = true

Subagent Tracing

Codex emits structured JSONL via --json (always enabled). Ralph TUI parses this to display:

Tool invocations and their output
Duration and status of each operation

Enabling Tracing

TOML

subagentTracingDetail = "full"

Or toggle in TUI:

Press t to cycle through detail levels
Press T (Shift+T) to toggle the subagent tree panel

How It Works

When Ralph TUI executes a task with Codex:

Build command: Constructs codex exec [options]
Pass prompt via stdin: Avoids shell escaping issues with special characters
Stream output: Captures stdout/stderr in real-time
Parse JSONL: Extracts structured tool call data (always enabled)
Detect completion: Watches for completion token
Handle exit: Reports success, failure, or timeout

CLI Arguments

Ralph TUI builds these arguments:

Bash

codex exec \
  --full-auto \                    # When fullAuto enabled
  --json \                         # Always used for structured output
  --model gpt-4 \                  # If model specified
  --sandbox workspace-write \      # Sandbox mode
  < prompt.txt                     # Prompt via stdin

Troubleshooting

"Codex CLI not found"

Ensure Codex is installed and in your PATH:

Bash

which codex
# Should output: /path/to/codex
 
# If not found, install:
npm install -g @openai/codex

"Execution timeout"

Increase the timeout for complex tasks:

TOML

[[agents]]
name = "codex"
plugin = "codex"
timeout = 600000  # 10 minutes

"Permission denied"

Check your sandbox mode. If Codex needs to modify files outside the workspace:

TOML

[agentOptions]
sandbox = "danger-full-access"

Next Steps

Claude Agent - Anthropic's Claude Code
Gemini Agent - Google's Gemini CLI
Configuration - Full options reference