codex-cli

⚠️ Environment Notice

| Environment | Git Repo | Command Format | |-------------|----------|----------------| | Interactive terminal | Any | codex "prompt" | | Claude Code / CI | ✅ Yes | codex exec -s read-only "prompt" | | Claude Code / CI | ❌ No | codex exec --skip-git-repo-check -s read-only "prompt" |

Non-TTY environments (Claude Code, CI pipelines, scripts) require codex exec.

Git Repository Detection

Before executing Codex commands, check if the working directory is a Git repository:

# Check Git repository status
git rev-parse --git-dir 2>/dev/null && echo "Git repo: YES" || echo "Git repo: NO"

• Git repo exists: Use standard commands
• No Git repo: Add --skip-git-repo-check flag (requires user awareness of security implications)

Quick Start

In Git Repository (Standard)

# Basic code review (terminal)
codex "Review this code for bugs"

# Non-interactive mode (Claude Code/CI)
codex exec -s read-only "Review this code for bugs"

# With specific model and reasoning effort
codex exec -s read-only -m gpt-5.3-codex -c model_reasoning_effort=high "Deep analysis"

# With image input
codex exec -s read-only -i screenshot.png "What's shown here?"

Outside Git Repository

# IMPORTANT: --skip-git-repo-check required for non-Git directories
# Ask user permission before using this flag

codex exec --skip-git-repo-check -s read-only "Review this code for bugs"

# With options
codex exec --skip-git-repo-check -s read-only -m gpt-5.3-codex "Deep analysis"

Session Resume (Special Syntax)

# IMPORTANT: Options must come BEFORE 'resume' subcommand
# SESSION_ID is from previous command output (e.g., 019ae3a3-f1cf-7dc1-8eee-8f424ae7a6f0)

# In Git repository
codex exec -s read-only resume [SESSION_ID] "Continue the analysis"

# Outside Git repository
codex exec --skip-git-repo-check -s read-only resume [SESSION_ID] "Continue the analysis"

Reference Documentation

• Commands Reference - codex, resume, apply, input/output patterns
• Options Reference - Models, sandbox, reasoning effort, approval modes
• Examples - Code review, security analysis, automation scripts

Available Models

Full model details: See Options Reference

Note: Model names change frequently as OpenAI releases new versions. Run codex --help or check OpenAI Codex Models for the current list.

| Model | Best For | |-------|----------| | gpt-5.3-codex | Most capable agentic coding model (recommended) | | gpt-5.2 | General AI tasks, multi-domain | | gpt-5.1-codex-max | Long-horizon agentic coding, security audits | | gpt-5-codex-mini | Quick checks, batch operations (cost-effective) |

Reasoning Effort

Usage examples: See Options Reference

| Level | Use Case | |-------|----------| | low | Simple checks, syntax review | | medium | Standard code review (default) | | high | Security audits, complex logic | | xhigh | Critical systems, exhaustive analysis |

Sandbox Modes

| Mode | Description | |------|-------------| | read-only | Cannot modify files (safest, recommended) | | workspace-write | Can modify workspace files | | danger-full-access | Full system access (use sparingly) |

Key Options

Full options list: See Options Reference

Common Patterns

Full examples: See Examples for detailed patterns

Essential Patterns

# Code review (Claude Code/CI)
codex exec -s read-only "Review: $(cat src/auth.js)"

# Maximum depth analysis
codex exec -m gpt-5.3-codex -c model_reasoning_effort=xhigh -s read-only "Security audit"

# Session continuity
codex exec -s read-only resume [SESSION_ID] "Continue analysis"

# Cross-directory
codex exec -C ./backend --add-dir ./frontend -s read-only "Review API"

# Non-Git directory (ask user first)
codex exec --skip-git-repo-check -s read-only "Analyze code"

Platform-Specific Notes

Windows Limitations

| Issue | Description | Workaround | |-------|-------------|------------| | -C with absolute paths | cwd is not absolute error with Windows paths like C:\path | Use relative paths (./subdir) or run from target directory | | Path separators | Backslashes may cause issues | Use forward slashes (/) in paths |

# AVOID on Windows:
codex exec -C C:\Projects\myapp -s read-only "analyze"

# USE instead:
cd C:\Projects\myapp && codex exec -s read-only "analyze"
# OR use relative paths:
codex exec -C ./myapp -s read-only "analyze"

Error Handling

Error recovery patterns: See Examples

| Error | Cause | Solution | |-------|-------|----------| | stdin is not a terminal | Using codex in non-TTY | Use codex exec | | Not inside a trusted directory | Not in Git repo | Ask user, then use --skip-git-repo-check | | invalid value for '--ask-for-approval' | Invalid approval value | Use: untrusted, on-failure, on-request, never | | unexpected argument after resume | Options after resume | Place options BEFORE resume subcommand | | cwd is not absolute | Windows absolute path | Use relative paths or cd first | | No prompt provided via stdin | Empty prompt | Ensure prompt string is not empty |

Timeout Configuration

| Task Type | Recommended Timeout | Claude Code Tool | |-----------|---------------------|------------------| | Quick checks | 2 minutes | timeout: 120000 | | Standard review | 5 minutes | timeout: 300000 | | Deep analysis | 10 minutes | timeout: 600000 |

Recommendation: Use timeout: 600000 for all Codex exec commands (model_reasoning_effort=high/xhigh can take 3-7 minutes).

Best Practices

1. Use codex exec in Claude Code and CI environments (non-TTY)
2. Default to -s read-only for all review tasks
3. Match model + reasoning effort to task complexity
4. Use resume to maintain session context
5. Use --add-dir for cross-project context
6. Use --full-auto only in controlled environments
7. Ask user before --skip-git-repo-check - explain implications
8. Check valid approval values - only use untrusted/on-failure/on-request/never
9. Set 10-minute timeout for all Codex exec commands (timeout: 600000)