Codex CLI

Use Codex CLI as a deterministic, non-interactive worker suitable for automation and agent orchestration.

Operating Rules

1. Use codex exec, not the interactive codex TUI.
2. Pass the task as the positional PROMPT argument. Do not use -p for the prompt; -p selects a profile.
3. For ordinary unattended code changes, prefer:

codex exec \
  -C /path/to/repo \
  --sandbox workspace-write \
  --ask-for-approval never \
  "<TASK>"

4. Use --yolo only inside an externally hardened and disposable runner. It disables Codex approvals and sandboxing.
5. For harnesses and CI, prefer --json plus --output-last-message.
6. Do not make the run depend on a human answering questions. Resolve ambiguity using repository evidence and conservative defaults.
7. Treat credentials as secrets. Inject CODEX_API_KEY only into the single codex exec process when possible.
8. Before giving version-sensitive advice, inspect codex exec --help or current official Codex documentation if available.
9. On Windows, choose one execution environment per task: native PowerShell for Windows toolchains or WSL2 for Linux toolchains. Do not casually mix paths, installations, or authentication across them.

Choose the Execution Mode

Read-only analysis

Use when the task must not modify files:

codex exec \
  -C /path/to/repo \
  --sandbox read-only \
  --ask-for-approval never \
  "Analyze the repository and report risks. Do not modify files."

Workspace-scoped implementation

Use as the default for autonomous repository work:

codex exec \
  -C /path/to/repo \
  --sandbox workspace-write \
  --ask-for-approval never \
  "Implement the task, run relevant tests, and report unresolved blockers."

Externally isolated unrestricted execution

Use only when the enclosing container, VM, or sandbox enforces the real security boundary:

codex exec \
  -C /workspace/repo \
  --yolo \
  "Implement the task and validate the result."

Never recommend --yolo on a normal developer machine or a runner containing unrelated secrets, host mounts, SSH keys, cloud credentials, or a Docker socket.

Construct an Autonomous Prompt

When headless execution could encounter choices, prepend these instructions:

Work fully autonomously.

Do not ask the user questions and do not request interactive input.
Inspect the repository and available context before making assumptions.
When several valid approaches exist, choose the option that:
1. minimizes unrelated changes,
2. preserves backward compatibility,
3. introduces the fewest new dependencies,
4. avoids destructive or irreversible actions.

Continue until the task is complete or a concrete blocking error is reached.
Record assumptions, validation performed, and unresolved blockers in the final response.

Do not simulate "always select the first option." Option ordering is not a safety or quality policy. Apply the explicit decision rules above instead.

Handle request_user_input Failures

When Codex reports that request_user_input is unavailable in Default mode or non-interactive mode:

1. Confirm the invocation uses codex exec and is intentionally headless.
2. Add the autonomous prompt policy above.
3. Supply missing decisions in the task prompt or AGENTS.md when they are known in advance.
4. Replace open-ended requests such as "ask me which approach" with deterministic selection criteria.
5. If the choice is safety-critical, destructive, or impossible to infer, make the run fail clearly rather than selecting randomly.
6. Do not attempt to emulate terminal keystrokes unless the subprocess itself, rather than Codex, requires input and the workflow explicitly defines the safe answer.

Pass Prompts and Context

Use a direct positional prompt:

codex exec "Summarize the repository structure."

Read the prompt from stdin:

codex exec - < prompt.md

Pipe dynamic context while retaining an explicit task:

npm test 2>&1 | codex exec "Analyze this test output and fix the repository."

Use --skip-git-repo-check only for intentional one-off directories outside Git:

codex exec \
  --skip-git-repo-check \
  -C /tmp/task \
  "Analyze the files in this directory."

Produce Harness-Friendly Output

Capture only the final message

codex exec \
  -C /workspace/repo \
  --output-last-message /output/final.md \
  "Review the codebase."

Stream JSONL events

codex exec \
  -C /workspace/repo \
  --json \
  --sandbox workspace-write \
  --ask-for-approval never \
  "Run tests and fix failures." \
  > /output/events.jsonl

Expect event families such as thread.started, turn.started, turn.completed, turn.failed, item.*, and error.

Capture events and the final answer together

codex exec \
  -C /workspace/repo \
  --json \
  --sandbox workspace-write \
  --ask-for-approval never \
  --output-last-message /output/final.md \
  "Complete the task autonomously." \
  | tee /output/events.jsonl

Do not parse human-readable progress text when --json is available.

Require Structured Final Output

Create a JSON Schema and pass it with --output-schema:

codex exec \
  -C /workspace/repo \
  --sandbox workspace-write \
  --ask-for-approval never \
  --output-schema /input/result.schema.json \
  --output-last-message /output/result.json \
  "Implement the task, validate it, and return the requested structured result."

A useful harness schema usually includes:

• status: success, partial, or failed
• summary: concise outcome
• changed_files: repository-relative paths
• validation: commands run and results
• assumptions: decisions made without user input
• blockers: concrete unresolved problems

Set additionalProperties to false when downstream parsing must be strict.

Resume or Avoid Persistence

Resume the most recent session for the current working directory:

codex exec resume --last "Continue the previous task and fix remaining issues."

Resume a specific session:

codex exec resume "$SESSION_ID" "Continue with the next stage."

Use an ephemeral run when rollout persistence is undesirable:

codex exec --ephemeral "Analyze the repository."

Do not rely on --last across unrelated working directories unless deliberately using the relevant all-directory option supported by the installed CLI.

Authenticate Safely

For a local interactive login:

codex login

For a headless machine with device-code login enabled:

codex login --device-auth

For a single automated invocation:

CODEX_API_KEY="$OPENAI_API_KEY" \
codex exec --json "Triage the repository."

Do not expose API keys as broad job-level environment variables in jobs that execute repository-controlled code. Never commit or print ~/.codex/auth.json.

Windows, PowerShell, and WSL2

For native Windows headless use:

• Install with the official PowerShell installer or npm.
• Prefer PowerShell 7.4 or newer for JSONL redirection.
• Build argument arrays and invoke them with & codex @args; avoid fragile backtick-heavy command construction.
• Check $LASTEXITCODE after every Codex invocation. PowerShell error preferences alone are not a substitute for checking a native process exit code.
• Keep stdout JSONL separate from stderr diagnostics. Do not use 2>&1 when stdout must remain parseable JSONL.
• Configure %USERPROFILE%\.codex\config.toml with [windows] sandbox = "elevated" when available; use unelevated only as the fallback.
• Preserve the task-level policy --sandbox workspace-write --ask-for-approval never for ordinary autonomous edits. The native Windows sandbox implementation and the CLI task policy are separate controls.

For WSL:

• Use WSL2, not WSL1.
• Install and authenticate Codex inside WSL as a Linux installation.
• Keep repositories under ~/code/..., not /mnt/c/..., for better performance and fewer permission, symlink, and file-watcher problems.
• Do not pass credentials through visible wsl.exe command-line strings.

See references/windows.md for installation, PowerShell wrappers, JSONL parsing, sandbox configuration, WSL2 patterns, and Windows-specific troubleshooting.

Container and CI Requirements

When generating a Docker, Kubernetes, or CI design:

• Mount only the intended workspace and output directory.
• Run as a non-root user when practical.
• Do not mount the host Docker socket.
• Do not mount home directories, SSH keys, or cloud credential directories.
• Restrict network access unless the task explicitly needs it.
• Apply CPU, memory, process, and execution-time limits outside Codex.
• Preserve stdout, stderr, exit status, JSONL events, and the final message separately.
• Validate repository diffs and test results before treating a run as successful.
• Prefer a fresh worktree or disposable checkout per task.

See references/recipes.md for ready-to-use shell, Docker, CI, and parser patterns.

Diagnose Failures

Use this order:

1. Run codex --version and codex exec --help.
2. Verify the command uses a positional prompt or - for stdin.
3. Verify the working directory and Git repository status.
4. Verify authentication without printing secret material.
5. Check whether sandbox policy blocks required reads, writes, commands, sockets, or network access.
6. Check whether approval policy is causing an impossible prompt in headless mode.
7. Inspect stderr and the JSONL error or turn.failed events.
8. Re-run with a smaller, deterministic task that reproduces the failure.
9. Do not silently switch to --yolo as a troubleshooting shortcut.

Completion Standard

For implementation tasks, consider the run complete only when Codex has:

1. inspected the relevant repository context,
2. made the requested changes,
3. run the most relevant available validation,
4. reviewed the resulting diff for unrelated changes,
5. reported assumptions and unresolved blockers,
6. produced machine-readable status when requested by the harness.