sundial-org/codex

Codex CLI (Non-Interactive)

Codex is OpenAI's coding agent. Use codex exec to run it non-interactively from any cli agent.

When to Use Codex

Use Codex when:

• Parallel work: Delegate a task while continuing other work
• Second opinion: Get an independent implementation or review
• Long-running tasks: Offload tasks that may take many iterations
• Code review: Use codex exec review for PR/diff reviews

Do NOT use Codex for:

• Simple file reads/edits you can do directly
• Tasks requiring back-and-forth conversation
• Tasks needing your current context

Quick Reference

# Analysis (read-only, default)
codex exec "describe the architecture of this codebase"

# Allow file edits
codex exec --full-auto "fix the failing tests"

# Code review
codex exec review --uncommitted
codex exec review --base main

# Structured JSON output
codex exec --output-schema schema.json -o result.json "extract metadata"

# Continue previous session (inherits original sandbox settings)
codex exec resume --last "now add tests"

Core Concepts

Output Streams

Progress goes to stderr, final result to stdout. To capture only the result:

codex exec "summarize the repo" 2>/dev/null > summary.txt

To see progress while capturing result:

codex exec "generate changelog" 2>&1 | tee output.txt

Sandbox Modes

In non-interactive mode, no approval prompts are possible. Permissions must be set upfront:

| Mode | Flag | Behavior | |------|------|----------| | Read-only | (default) | Reads anywhere, writes/commands blocked | | Workspace-write | --full-auto | Pre-approves edits and commands in workspace | | Full access | --yolo | No restrictions. Use in isolated environments only |

Choose based on task:

• Analysis/explanation → default (read-only)
• Fix bugs/implement features → --full-auto
• Needs network or system access → --yolo (dangerous)

Note: ~/.codex/config.toml can set project trust levels that override defaults.

Models

Default model is gpt-5.2-codex. Override with -m:

codex exec -m gpt-5 "explain this code"

Authentication

By default, the user should already be authenticated. If not, set CODEX_API_KEY:

CODEX_API_KEY=sk-... codex exec "task"

Code Review

Built-in review subcommand:

# Review uncommitted changes
codex exec review --uncommitted

# Review against a base branch
codex exec review --base main

# Review a specific commit
codex exec review --commit abc123

Structured Output

Use --output-schema for JSON output. Important: OpenAI requires additionalProperties: false on all object types.

codex exec --output-schema schema.json -o result.json "extract API endpoints"

Schema example:

{
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "endpoints": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "path": { "type": "string" },
          "method": { "type": "string" }
        },
        "required": ["path", "method"],
        "additionalProperties": false
      }
    }
  },
  "required": ["name", "endpoints"],
  "additionalProperties": false
}

Session Resume

Resume continues a previous session, inheriting its sandbox settings:

# Start a task
codex exec --full-auto "implement rate limiter"

# Continue later (inherits --full-auto from original)
codex exec resume --last "add unit tests"

# Or resume by session ID
codex exec resume <SESSION_ID> "follow-up task"

Note: Cannot pass --full-auto to resume; it inherits from the original session.

JSONL Event Stream

For programmatic use, --json outputs structured events:

codex exec --json "analyze code" 2>/dev/null | jq -c 'select(.type == "item.completed")'

Performance & Best Practices

Execution Time

Complex tasks typically take 60-120+ seconds. Simple analysis tasks complete in 10-30 seconds.

• Tasks may continue executing even after your timeout
• Always check if files were modified regardless of timeout status
• Use tail -f <output_file> to monitor long-running background tasks

Task Granularity

Break complex work into focused tasks:

# Good: Focused, single-purpose tasks
codex exec --full-auto "add star ratings to the skill cards"
codex exec --full-auto "add a search filter to the toolbar"

# Avoid: Multi-feature requests in one task
codex exec --full-auto "add ratings, search, filters, modal, and animations"

Concurrent Editing

Avoid running multiple Codex sessions on the same file simultaneously. While it may work, concurrent edits risk merge conflicts or overwrites.

Large Files

Files over ~2000 lines slow execution as Codex reads the entire file multiple times. Consider:

• Splitting into multiple files when possible
• Using specific line references in prompts
• Breaking incremental changes into smaller tasks

Error Handling

Common errors:

• Timeout: Long tasks may timeout. Check if work completed anyway, or use resume to continue.
• Sandbox blocked: Task needs writes but running in read-only. Use --full-auto.
• Schema validation: Missing additionalProperties: false in schema objects.
• Model not supported: Some models unavailable with ChatGPT auth. Use default gpt-5.2-codex.

Detailed References

• exec-reference.md: Complete flag reference
• prompting.md: Effective prompts and workflow patterns

Project Context

Codex reads AGENTS.md files for project instructions:

• ~/.codex/AGENTS.md - Global defaults
• <repo>/AGENTS.md - Project-specific

# AGENTS.md
- Run `npm test` after modifying JS files
- Use pnpm for dependencies