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-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

• Use codex exec in Claude Code and CI environments (non-TTY)

• Default to -s read-only for all review tasks

• Match model + reasoning effort to task complexity

• Use resume to maintain session context

• Use --add-dir for cross-project context

• Use --full-auto only 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 )