majiayu000 Codex CLI Skill
⚠️ 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-checkflag (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.2-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.2-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
| Model | Best For |
|---|---|
gpt-5.2-codex |
Complex analysis, critical systems (recommended) |
gpt-5.2 |
General AI tasks, multi-domain |
gpt-5.1-codex-max |
Security audits, architecture review |
gpt-5.1-codex-mini |
Quick checks, batch operations |
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.2-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
- Use
codex execin Claude Code and CI environments (non-TTY) - Default to
-s read-onlyfor all review tasks - Match model + reasoning effort to task complexity
- Use
resumeto maintain session context - Use
--add-dirfor cross-project context - Use
--full-autoonly in controlled environments - Ask user before
--skip-git-repo-check- explain implications - Check valid approval values - only use
untrusted/on-failure/on-request/never - Set 10-minute timeout for all Codex exec commands (
timeout: 600000)