Codex: High-Reasoning AI Assistant for Claude Code

---

CRITICAL: Always Use codex exec

MUST USE: codex exec for ALL Codex CLI invocations in Claude Code.

NEVER USE: codex (interactive mode) - will fail with "stdout is not a terminal" ALWAYS USE: codex exec (non-interactive mode)

Examples:

• codex exec -m gpt-5.2 "prompt" (CORRECT)
• codex -m gpt-5.2 "prompt" (WRONG - will fail)
• codex exec resume --last (CORRECT)
• codex resume --last (WRONG - will fail)

Why? Claude Code's bash environment is non-terminal/non-interactive. Only codex exec works in this environment.

---

When to Use This Skill

This skill should be invoked when:

• User explicitly mentions "Codex" or requests Codex assistance
• User needs help with complex coding tasks, algorithms, or architecture
• User requests "high reasoning" or "advanced implementation" help
• User needs complex problem-solving or architectural design
• User wants to continue a previous Codex conversation

How It Works

Detecting New Codex Requests

When a user makes a request that falls into one of the above categories, determine the task type:

General Tasks (architecture, design, reviews, explanations):

• Use model: gpt-5.2 (high-reasoning general model)
• Example requests: "Design a queue data structure", "Review this architecture", "Explain this algorithm"

Code Editing Tasks (file modifications, implementation):

• Use model: gpt-5.2-codex-max (maximum capability for code editing - 27-42% faster)
• Example requests: "Edit this file to add feature X", "Implement the function", "Refactor this code"

Bash CLI Command Structure

IMPORTANT: Always use codex exec for non-interactive execution. Claude Code's bash environment is non-terminal, so the interactive codex command will fail with "stdout is not a terminal" error.

For General Reasoning Tasks (Default)

codex exec -m gpt-5.2 -s read-only \
  -c model_reasoning_effort=high \
  --enable web_search_request \
  "<user's prompt>"

For Code Editing Tasks

codex exec -m gpt-5.2-codex-max -s workspace-write \
  -c model_reasoning_effort=high \
  --enable web_search_request \
  "<user's prompt>"

Why codex exec?

• Non-interactive mode required for automation and Claude Code integration
• Produces clean output suitable for parsing
• Works in non-TTY environments (like Claude Code's bash)

Model Selection Logic

Use gpt-5.2 (default) when:

• Designing architecture or data structures
• Reviewing code for quality, security, or performance
• Explaining concepts or algorithms
• Planning implementation strategies
• General problem-solving and reasoning

Use gpt-5.2-codex-max when:

• Editing or modifying existing code files
• Implementing specific functions or features
• Refactoring code
• Writing new code with file I/O
• Any task requiring workspace-write sandbox
• Complex code editing requiring maximum reasoning capability

Note: For backward compatibility, gpt-5.2-codex (standard model) is still available and works identically. Use gpt-5.2-codex-max as the default for better performance (27-42% faster, 30% fewer thinking tokens).

Default Configuration

All Codex invocations use these defaults unless user specifies otherwise:

Parameter	Default Value	CLI Flag	Notes
Model	gpt-5.2	-m gpt-5.2	General reasoning tasks
Model (code editing)	gpt-5.2-codex-max	-m gpt-5.2-codex-max	Code editing tasks (27-42% faster)
Sandbox	read-only	-s read-only	Safe default (general tasks)
Sandbox (code editing)	workspace-write	-s workspace-write	Allows file modifications
Reasoning Effort	high	-c model_reasoning_effort=high	Maximum reasoning capability
Verbosity	medium	-c model_verbosity=medium	Balanced output detail
Web Search	enabled	--enable web_search_request	Access to up-to-date information

CLI Flags Reference

Codex CLI Version: 0.59.0+ (requires 0.59.0+ for gpt-5.2-codex-max support)

Flag	Values	Description
-m, --model	gpt-5.2, gpt-5.2-codex, gpt-5.2-codex-max	Model selection
-s, --sandbox	read-only, workspace-write, danger-full-access	Sandbox mode
-c, --config	key=value	Config overrides (e.g., model_reasoning_effort=high)
-C, --cd	directory path	Working directory
-p, --profile	profile name	Use config profile
--enable	feature name	Enable a feature (e.g., web_search_request)
--disable	feature name	Disable a feature
-i, --image	file path(s)	Attach image(s) to initial prompt
--full-auto	flag	Convenience for workspace-write sandbox with on-failure approval
--oss	flag	Use local open source model provider
--skip-git-repo-check	flag	Allow running outside Git repository
--output-schema	file path	JSON Schema file for response shape
--color	always, never, auto	Color settings for output
--json	flag	Print events as JSONL
-o, --output-last-message	file path	Save last message to file
--dangerously-bypass-approvals-and-sandbox	flag	Skip confirmations (DANGEROUS)

Configuration Parameters

Pass these as -c key=value:

• model_reasoning_effort: minimal, low, medium, high, xhigh (default: high)
  • xhigh: Extra-high reasoning for maximum capability (gpt-5.2-codex-max only)
  • Use xhigh for complex architectural refactoring, long-horizon tasks, or when quality is more important than speed
• model_verbosity: low, medium, high (default: medium)
• model_reasoning_summary: auto, concise, detailed, none (default: auto)
• sandbox_workspace_write.writable_roots: JSON array of additional writable directories (e.g., ["/path1","/path2"])

Note: To specify additional writable directories beyond the workspace, use:

-c 'sandbox_workspace_write.writable_roots=["/path1","/path2"]'

This replaces the removed --add-dir flag from earlier versions.

Model Selection Guide

Default Models (Codex CLI v0.59.0+)

This skill defaults to the gpt-5.2 model family:

• gpt-5.2 - General reasoning, architecture, reviews (default)

Performance Characteristics:

• gpt-5.2-codex-max is 27-42% faster than gpt-5.2-codex
• Uses ~30% fewer thinking tokens at the same reasoning effort level
• Supports new xhigh reasoning effort for maximum capability
• Requires Codex CLI 0.59.0+ and ChatGPT Plus/Pro/Business/Edu/Enterprise subscription

Backward Compatibility

You can override to use older models when needed:

# Use older gpt-5 model explicitly
codex exec -m gpt-5 -s read-only "Design a data structure"

# Use older gpt-5-codex model explicitly
codex exec -m gpt-5-codex -s workspace-write "Implement feature X"

When to Override

• Testing compatibility: Verify behavior matches older model versions
• Specific model requirements: Project requires specific model version
• Model comparison: Compare outputs between model versions

Model Override Examples

Override via -m flag:

# Override to gpt-5 for general task
codex exec -m gpt-5 "Explain algorithm complexity"

# Override to gpt-5-codex for code task
codex exec -m gpt-5-codex -s workspace-write "Refactor authentication"

# Override to gpt-4 if available
codex exec -m gpt-4 "Review this code"

Default Behavior

Without explicit -m override:

• General tasks → gpt-5.2
• Code editing tasks → gpt-5.2-codex-max (recommended for best performance)
• Backward compatibility → gpt-5.2-codex still works if explicitly specified

Session Continuation

Detecting Continuation Requests

When user indicates they want to continue a previous Codex conversation:

• Keywords: "continue", "resume", "keep going", "add to that"
• Follow-up context referencing previous Codex work
• Explicit request like "continue where we left off"

Resuming Sessions

For continuation requests, use the codex resume command:

Resume Most Recent Session (Recommended)

codex exec resume --last

This automatically continues the most recent Codex session with all previous context maintained.

Resume Specific Session

codex exec resume <session-id>

Resume a specific session by providing its UUID. Get session IDs from previous Codex output or by running codex exec resume --last to see the most recent session.

Note: The interactive session picker (codex resume without arguments) is NOT available in non-interactive/Claude Code environments. Always use --last or provide explicit session ID.

Decision Logic: New vs. Continue

Use codex exec -m ... "<prompt>" when:

• User makes a new, independent request
• No reference to previous Codex work
• User explicitly wants a "fresh" or "new" session

Use codex exec resume --last when:

• User indicates continuation ("continue", "resume", "add to that")
• Follow-up question building on previous Codex conversation
• Iterative development on same task

Session History Management

• Codex CLI automatically saves session history
• No manual session ID tracking needed
• Sessions persist across Claude Code restarts
• Use codex exec resume --last to access most recent session
• Use codex exec resume <session-id> for specific sessions

Error Handling

Simple Error Response Strategy

When errors occur, return clear, actionable messages without complex diagnostics:

Error Message Format:

Error: [Clear description of what went wrong]

To fix: [Concrete remediation action]

[Optional: Specific command example]

Common Errors

Command Not Found

Error: Codex CLI not found

To fix: Install Codex CLI and ensure it's available in your PATH

Check installation: codex --version

Authentication Required

Error: Not authenticated with Codex

To fix: Run 'codex login' to authenticate

After authentication, try your request again.

Invalid Configuration

Error: Invalid model specified

To fix: Use 'gpt-5.2' for general reasoning or 'gpt-5.2-codex-max' for code editing (gpt-5.2-codex also available for backward compatibility)

Example: codex exec -m gpt-5.2 "your prompt here"
Example: codex exec -m gpt-5.2-codex-max -s workspace-write "code editing task"

Troubleshooting

First Steps for Any Issues:

1. Check Codex CLI built-in help: codex --help, codex exec --help, codex exec resume --help
2. Consult official documentation: https://github.com/openai/codex/tree/main/docs
3. Verify skill resources in references/ directory

Skill not being invoked?

• Check that request matches trigger keywords (Codex, complex coding, high reasoning, etc.)
• Explicitly mention "Codex" in your request
• Try: "Use Codex to help me with..."

Session not resuming?

• Verify you have a previous Codex session (check command output for session IDs)
• Try: codex exec resume --last to resume most recent session
• If no history exists, start a new session first

"stdout is not a terminal" error?

• Always use codex exec instead of plain codex in Claude Code
• Claude Code's bash environment is non-interactive/non-terminal

Errors during execution?

• Codex CLI errors are passed through directly
• Check Codex CLI logs for detailed diagnostics
• Verify working directory permissions if using workspace-write
• Check official Codex docs for latest updates and known issues

Examples

Example 1: General Reasoning Task (Architecture Design)

User Request: "Help me design a binary search tree architecture in Rust"

Skill Executes:

codex exec -m gpt-5.2 -s read-only \
  -c model_reasoning_effort=high \
  "Help me design a binary search tree architecture in Rust"

Result: Codex provides high-reasoning architectural guidance using gpt-5. Session automatically saved for continuation.

---

Example 2: Code Editing Task

User Request: "Edit this file to implement the BST insert method"

Skill Executes:

codex exec -m gpt-5.2-codex-max -s workspace-write \
  -c model_reasoning_effort=high \
  "Edit this file to implement the BST insert method"

Result: Codex uses gpt-5.2-codex-max (maximum capability for coding - 27-42% faster) with workspace-write permissions to modify files.

---

Example 3: Session Continuation

User Request: "Continue with the BST - add a deletion method"

Skill Executes:

codex exec resume --last

Result: Codex resumes the previous BST session and continues with deletion method implementation, maintaining full context.

---

Example 4: Custom Configuration

User Request: "Use Codex with web search to research and implement async patterns"

Skill Executes:

codex exec -m gpt-5.2-codex-max -s workspace-write \
  -c model_reasoning_effort=high \
  --enable web_search_request \
  "Research and implement async patterns"

Result: Codex uses web search capability for latest information, then implements with high reasoning and maximum code editing capability.

---

Example 5: Maximum Reasoning with xhigh

User Request: "Perform complex architectural refactoring of authentication system"

Skill Executes:

codex exec -m gpt-5.2-codex-max -s workspace-write \
  -c model_reasoning_effort=xhigh \
  "Perform complex architectural refactoring of authentication system"

Result: Codex uses extra-high reasoning effort (xhigh) for maximum capability on complex long-horizon tasks. Ideal for architectural refactoring where quality is more important than speed.

---

New in v0.53.0

Feature Flags (--enable / --disable)

Enable or disable specific Codex features:

codex exec --enable web_search_request "Research latest patterns"
codex exec --disable some_feature "Run without feature"

Image Attachment (-i, --image)

Attach images to prompts for visual analysis:

codex exec -i screenshot.png "Analyze this UI design"
codex exec -i diagram1.png -i diagram2.png "Compare these architectures"

Non-Git Environments (--skip-git-repo-check)

Run Codex outside Git repositories:

codex exec --skip-git-repo-check "Help with this script"

Structured Output (--output-schema)

Define JSON schema for model responses:

codex exec --output-schema schema.json "Generate structured data"

Output Coloring (--color)

Control colored output (always, never, auto):

codex exec --color never "Run in CI/CD pipeline"

Web Search Migration

Deprecated: --search flag (not available in codex exec) New: Use --enable web_search_request instead

# Old (invalid for codex exec)
codex --search "research topic"

# New (correct)
codex exec --enable web_search_request "research topic"

---

When to Use gpt-5.2 vs gpt-5.2-Codex-Max

Use gpt-5.2 (General High-Reasoning) For:

• Architecture and system design
• Code reviews and quality analysis
• Security audits and vulnerability assessment
• Performance optimization strategies
• Algorithm design and analysis
• Explaining complex concepts
• Planning and strategy

Use gpt-5.2-Codex-Max (Maximum Code Capability) For:

• Editing existing code files (27-42% faster than standard codex)
• Implementing specific features
• Refactoring and code transformations
• Writing new code with file I/O
• Code generation tasks
• Debugging and fixes requiring file changes
• Complex architectural refactoring (with xhigh reasoning effort)

Use gpt-5.2-Codex (Standard Code Model) For:

• Backward compatibility scenarios
• When you need to replicate behavior from earlier versions
• Explicit requirement to use the standard (non-max) model

Default: When in doubt, use gpt-5.2 for general tasks. Use gpt-5.2-codex-max when specifically editing code for best performance and quality.

Best Practices

1. Use Descriptive Requests

Good: "Help me implement a thread-safe queue with priority support in Python" Vague: "Code help"

Clear, specific requests get better results from high-reasoning models.

2. Indicate Continuation Clearly

Good: "Continue with that queue implementation - add unit tests" Unclear: "Add tests" (might start new session)

Explicit continuation keywords help the skill choose the right command.

3. Specify Permissions When Needed

Good: "Refactor this code (allow file writing)" Risky: Assuming permissions without specifying

Make your intent clear when you need workspace-write permissions.

4. Leverage High Reasoning

The skill defaults to high reasoning effort - perfect for:

• Complex algorithms
• Architecture design
• Performance optimization
• Security reviews

Platform & Capabilities (v0.53.0)

Windows Sandbox Support

Windows sandbox is now available in alpha (experimental). Use with caution in production environments.

Interactive Mode Features

The /exit slash-command alias is available in interactive codex mode (not applicable to codex exec non-interactive mode used by this skill).

Model Verbosity Override

All code editing models (gpt-5.2-codex-max, gpt-5.2-codex) support verbosity override via -c model_verbosity=<level> for controlling output detail levels.

Pattern References

For command construction examples and workflow patterns, Claude can reference:

• references/command-patterns.md - Common codex exec usage patterns
• references/session-workflows.md - Session continuation and resume workflows
• references/advanced-patterns.md - Complex configuration and flag combinations

These files provide detailed examples for constructing valid codex exec commands for various scenarios.

Additional Resources

For more details, see:

• references/codex-help.md - Codex CLI command reference
• references/codex-config.md - Full configuration options
• README.md - Installation and quick start guide