Awesome-omni-skill codex
Invoke Codex CLI for complex coding tasks requiring high reasoning capabilities. Trigger phrases include "use codex", "ask codex", "run codex", "call codex", "codex cli", "GPT-5 reasoning", "OpenAI reasoning", or when users request complex implementation challenges, advanced reasoning, architecture design, or high-reasoning model assistance. Automatically triggers on codex-related requests and supports session continuation for iterative development.
git clone https://github.com/diegosouzapw/awesome-omni-skill
T=$(mktemp -d) && git clone --depth=1 https://github.com/diegosouzapw/awesome-omni-skill "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/development/codex" ~/.claude/skills/diegosouzapw-awesome-omni-skill-codex-01d59a && rm -rf "$T"
skills/development/codex/SKILL.mdCodex: High-Reasoning AI Assistant for Claude Code
DEFAULT MODEL: Task-Based Model Selection with Read-Only Default
Codex uses task-based model selection. Sandbox is
by default - only use read-only
when user explicitly requests file editing.workspace-write
| Task Type | Model | Sandbox (default) | Sandbox (explicit edit) |
|---|---|---|---|
| Code-related tasks | | read-only | workspace-write |
| General tasks | | read-only | workspace-write |
- Code-related tasks: Use
- optimized for agentic coding (56.4% SWE-Bench Pro)gpt-5.2-codex - General tasks: Use
- high-reasoning general modelgpt-5.2 - Sandbox default: Always
unless user explicitly requests editingread-only - Explicit editing: Only when user says "edit", "modify", "write changes", etc., use
workspace-write - Always use
for maximum capability-c model_reasoning_effort=xhigh
# Code task (read-only default) codex exec -m gpt-5.2-codex -s read-only \ -c model_reasoning_effort=xhigh \ "analyze this function implementation" # General task (read-only default) codex exec -m gpt-5.2 -s read-only \ -c model_reasoning_effort=xhigh \ "explain this architecture" # Code task with explicit edit request codex exec -m gpt-5.2-codex -s workspace-write \ -c model_reasoning_effort=xhigh \ "edit this file to add the feature" # General task with explicit edit request codex exec -m gpt-5.2 -s workspace-write \ -c model_reasoning_effort=xhigh \ "modify the documentation file"
Model Fallback Chain
If the primary model is unavailable, fallback gracefully:
- Code tasks:
→gpt-5.2-codex
→gpt-5.2gpt-5.1-codex-max - General tasks:
→gpt-5.2
→gpt-5.1gpt-5.1-codex-max - Reasoning effort:
→xhigh
→highmedium
CRITICAL: Always Use codex exec
codex execMUST 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:
(CORRECT)codex exec -m gpt-5.2 "prompt"
(WRONG - will fail)codex -m gpt-5.2 "prompt"
(CORRECT)codex exec resume --last
(WRONG - will fail)codex resume --last
Why? Claude Code's bash environment is non-terminal/non-interactive. Only
codex exec works in this environment.
IMPORTANT: Interactive vs Exec Mode Flags
Some Codex CLI flags are ONLY available in interactive mode, NOT in
.codex exec
| Flag | Interactive | | Alternative for exec |
|---|---|---|---|
| ✅ Available | ❌ NOT available | |
| ✅ Available | ❌ NOT available | or |
| ✅ Available | ✅ Available | N/A |
| ✅ Available | ✅ Available | N/A |
For web search in exec mode:
# CORRECT - works in codex exec codex exec --enable web_search_request "research topic" # WRONG - --search only works in interactive mode codex --search "research topic"
For approval control in exec mode:
# CORRECT - works in codex exec codex exec --full-auto "task" codex exec -c approval_policy=on-request "task" # WRONG - -a only works in interactive mode codex -a on-request "task"
Trigger Examples
This skill activates when users say phrases like:
- "Use codex to analyze this architecture"
- "Ask codex about this design decision"
- "Run codex on this problem"
- "Call codex for help with this implementation"
- "I need GPT-5 reasoning for this task"
- "Get OpenAI's high-reasoning model on this"
- "Continue with codex" or "Resume the codex session"
- "Codex, help me with..." or simply "Codex"
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, first determine the task type (code vs general), then determine sandbox based on explicit edit request:
Step 1: Determine Task Type (Model Selection)
- Code-related tasks: Use
- for implementation, refactoring, code analysis, debugging, etc.gpt-5.2-codex - General tasks: Use
- for architecture design, explanations, reviews, documentation, etc.gpt-5.2
Step 2: Determine Sandbox (Edit Permission)
- Default:
- safe for all tasks unless user explicitly requests editingread-only - Explicit edit request:
- ONLY when user explicitly says to edit/modify/write filesworkspace-write
Code-related task examples:
- Read-only: "Analyze this function", "Review this implementation", "Debug this code"
- With editing: "Edit this file to fix the bug", "Modify the function", "Refactor and save"
General task examples:
- Read-only: "Design a queue data structure", "Explain this algorithm", "Review the architecture"
- With editing: "Update the documentation file", "Modify the README"
⚠️ Important: The key distinction for sandbox is whether the user explicitly asks for file modifications. Use
workspace-write ONLY when user says "edit", "modify", "write changes", "save", etc.
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.
Code Task (Read-Only Default)
codex exec -m gpt-5.2-codex -s read-only \ -c model_reasoning_effort=xhigh \ --enable web_search_request \ "<code-related prompt>"
General Task (Read-Only Default)
codex exec -m gpt-5.2 -s read-only \ -c model_reasoning_effort=xhigh \ --enable web_search_request \ "<general prompt>"
Code Task with Explicit Edit Request
codex exec -m gpt-5.2-codex -s workspace-write \ -c model_reasoning_effort=xhigh \ --enable web_search_request \ "<edit code prompt>"
General Task with Explicit Edit Request
codex exec -m gpt-5.2 -s workspace-write \ -c model_reasoning_effort=xhigh \ --enable web_search_request \ "<edit general files 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
Step 1: Choose Model Based on Task Type
Use
for code-related tasks:gpt-5.2-codex
- Implementation, refactoring, code analysis
- Debugging, fixing bugs, optimization
- Any task involving code understanding or modification
Use
for general tasks:gpt-5.2
- Architecture and system design
- Explanations, documentation, reviews
- Planning, strategy, general reasoning
Step 2: Choose Sandbox Based on Edit Intent
Use
(DEFAULT):read-only
- Analysis, review, explanation tasks
- ANY task where user does NOT explicitly request file editing
Use
(ONLY when explicitly requested):workspace-write
- User explicitly says "edit this file", "modify the code", "write changes"
- User explicitly asks to "make edits" or "save the changes"
- User explicitly requests "refactor and save" or "implement and write"
Fallback Models:
gpt-5.1-codex-max and gpt-5.1 are available if primary models are unavailable. See fallback chain in DEFAULT MODEL section.
Default Configuration
All Codex invocations use these defaults unless user specifies otherwise:
| Parameter | Default Value | CLI Flag | Notes |
|---|---|---|---|
| Model (code tasks) | | | For code-related tasks |
| Model (general tasks) | | | For general tasks |
| Sandbox (default) | | | Safe default for ALL tasks |
| Sandbox (explicit edit) | | | Only when user explicitly requests editing |
| Reasoning Effort | | | Maximum reasoning capability |
| Verbosity | | | Balanced output detail |
| Web Search | | | Access to up-to-date information |
CLI Flags Reference
Codex CLI Version: 0.72.0+ (requires 0.72.0+ for gpt-5.2-codex and xhigh)
| Flag | Values | Description |
|---|---|---|
| , , , | Model selection |
| , , | Sandbox mode |
| | Config overrides (e.g., ) |
| directory path | Working directory |
| profile name | Use config profile |
| feature name | Enable a feature (e.g., ) |
| feature name | Disable a feature |
| file path(s) | Attach image(s) to initial prompt |
| directory path | Additional writable directory (repeatable) |
| flag | Convenience for workspace-write sandbox with on-request approval |
| flag | Use local open source model provider |
| , | Specify local provider (with --oss) |
| flag | Allow running outside Git repository |
| file path | JSON Schema file for response shape |
| , , | Color settings for output |
| flag | Print events as JSONL |
| file path | Save last message to file |
| flag | Skip confirmations (DANGEROUS) |
Configuration Parameters
Pass these as
-c key=value:
:model_reasoning_effort
,minimal
,low
,medium
,highxhigh- CLI default:
- The Codex CLI defaults to high reasoninghigh - Skill default:
- This skill explicitly uses xhigh for maximum capabilityxhigh
: Extra-high reasoning for maximum capability (supported by gpt-5.2 and gpt-5.1-codex-max)xhigh- Use
for complex architectural refactoring, long-horizon tasks, or when quality is more important than speedxhigh
- CLI default:
:model_verbosity
,low
,medium
(default:high
)medium
:model_reasoning_summary
,auto
,concise
,detailed
(default:none
)auto
: JSON array of additional writable directories (e.g.,sandbox_workspace_write.writable_roots
)["/path1","/path2"]
:approval_policy
,untrusted
,on-failure
,on-request
(approval behavior)never
Additional Writable Directories:
Use
--add-dir flag (preferred) or config:
# Preferred - simpler syntax (v0.71.0+) codex exec --add-dir /path1 --add-dir /path2 "task" # Alternative - config approach codex exec -c 'sandbox_workspace_write.writable_roots=["/path1","/path2"]' "task"
Model Selection Guide
Default Models (Codex CLI v0.71.0+)
This skill supports the following models:
- Latest model with all reasoning levels (NEW in 0.71.0)gpt-5.2
- General reasoning, architecture, reviews (default)gpt-5.1
- Code editing (legacy, use gpt-5.2 instead)gpt-5.1-codex-max
- Standard code editing (available for backward compatibility)gpt-5.1-codex
GPT-5.2 Model (NEW):
- Supports all reasoning effort levels:
,low
,medium
,highxhigh - Use for cutting-edge tasks requiring latest model capabilities
- Example:
codex exec -m gpt-5.2 -c model_reasoning_effort=xhigh "complex task"
Performance Characteristics:
is 27-42% faster thangpt-5.1-codex-maxgpt-5.1-codex- Uses ~30% fewer thinking tokens at the same reasoning effort level
- Supports new
reasoning effort for maximum capabilityxhigh - Requires Codex CLI 0.71.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:
- All tasks →
(latest model, recommended default)gpt-5.2 - General reasoning →
(if explicitly requested)gpt-5.1 - Backward compatibility →
andgpt-5.1-codex-max
still work if explicitly specifiedgpt-5.1-codex
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
when:codex exec -m ... "<prompt>"
- User makes a new, independent request
- No reference to previous Codex work
- User explicitly wants a "fresh" or "new" session
Use
when:codex exec resume --last
- 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
to access most recent sessioncodex exec resume --last - Use
for specific sessionscodex exec resume <session-id>
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: - For coding tasks: Use 'gpt-5.2-codex' with workspace-write sandbox - For reasoning tasks: Use 'gpt-5.2' with read-only sandbox Example (coding): codex exec -m gpt-5.2-codex -s workspace-write -c model_reasoning_effort=xhigh "implement feature" Example (reasoning): codex exec -m gpt-5.2 -s read-only -c model_reasoning_effort=xhigh "explain architecture"
Troubleshooting
First Steps for Any Issues:
- Check Codex CLI built-in help:
,codex --help
,codex exec --helpcodex exec resume --help - Consult official documentation: https://github.com/openai/codex/tree/main/docs
- Verify skill resources in
directoryreferences/
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:
to resume most recent sessioncodex exec resume --last - If no history exists, start a new session first
"stdout is not a terminal" error?
- Always use
instead of plaincodex exec
in Claude Codecodex - 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: Code Task (Read-Only Default)
User Request: "Analyze this function implementation and suggest improvements"
Skill Executes:
codex exec -m gpt-5.2-codex -s read-only \ -c model_reasoning_effort=xhigh \ "Analyze this function implementation and suggest improvements"
Result: Code-related task uses gpt-5.2-codex with read-only sandbox (default). No file modifications.
Example 2: General Task (Read-Only Default)
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=xhigh \ "Help me design a binary search tree architecture in Rust"
Result: General task uses gpt-5.2 with read-only sandbox (default). Session automatically saved for continuation.
Example 3: Code Task with Explicit Edit Request
User Request: "Edit this file to implement the BST insert method"
Skill Executes:
codex exec -m gpt-5.2-codex -s workspace-write \ -c model_reasoning_effort=xhigh \ "Edit this file to implement the BST insert method"
Result: User explicitly said "Edit this file" - code task uses gpt-5.2-codex with workspace-write permissions.
Example 4: 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 5: With Web Search (Read-Only Default)
User Request: "Use Codex with web search to research async patterns"
Skill Executes:
codex exec -m gpt-5.2-codex -s read-only \ -c model_reasoning_effort=xhigh \ --enable web_search_request \ "Research async patterns"
Result: Code-related research uses gpt-5.2-codex with read-only sandbox (default) and web search enabled.
Example 6: Explicit Refactoring Request
User Request: "Refactor and save the authentication system code"
Skill Executes:
codex exec -m gpt-5.2-codex -s workspace-write \ -c model_reasoning_effort=xhigh \ "Refactor and save the authentication system code"
Result: User explicitly said "Refactor and save" - code task uses gpt-5.2-codex with workspace-write for file modifications.
Code Review Subcommand (v0.71.0+)
The
codex review subcommand provides non-interactive code review capabilities:
# Review uncommitted changes (staged, unstaged, untracked) codex review --uncommitted # Review changes against a base branch codex review --base main # Review a specific commit codex review --commit abc123 # Review with custom instructions codex review --uncommitted "Focus on security vulnerabilities" # Non-interactive via exec codex exec review --uncommitted
Review Options:
| Flag | Description |
|---|---|
| Review staged, unstaged, and untracked changes |
| Review changes against the given base branch |
| Review the changes introduced by a commit |
| Optional commit title for review summary |
CLI Features Reference
Feature Flags (--enable
/ --disable
)
--enable--disableEnable 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
)
-i, --imageAttach 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"
Additional Directories (--add-dir
) (v0.71.0+)
--add-dirAdd writable directories beyond the primary workspace:
codex exec --add-dir /shared/libs --add-dir /config "task"
Full Auto Mode (--full-auto
)
--full-autoConvenience flag for low-friction execution:
codex exec --full-auto "task" # Equivalent to: -s workspace-write with on-request approval
Non-Git Environments (--skip-git-repo-check
)
--skip-git-repo-checkRun Codex outside Git repositories:
codex exec --skip-git-repo-check "Help with this script"
Structured Output (--output-schema
)
--output-schemaDefine JSON schema for model responses:
codex exec --output-schema schema.json "Generate structured data"
Output Coloring (--color
)
--colorControl colored output (always, never, auto):
codex exec --color never "Run in CI/CD pipeline"
Web Search in Exec Mode
Note:
--search flag is interactive-only. Use --enable for exec mode:
# CORRECT for codex exec codex exec --enable web_search_request "research topic" # WRONG - --search only works in interactive mode codex --search "research topic"
Feature Flags (codex features list
) (v0.71.0+)
codex features listInspect and manage Codex feature flags:
# List all feature flags with their states codex features list
Current Feature Flags (as of v0.71.0):
Stable Features:
| Feature | Default | Description |
|---|---|---|
| false | Enable web search capability |
| true | Parallel execution |
| true | Shell command execution |
| true | Undo functionality |
| true | Image viewing capability |
| true | Display warnings |
Experimental/Beta Features:
| Feature | Stage | Default | Description |
|---|---|---|---|
| experimental | true | Execution policy control |
| experimental | true | Remote compaction |
| experimental | false | Unified execution mode |
| experimental | false | RMCP client support |
| beta | false | Freeform patch application |
| experimental | false | Skills support |
| experimental | false | Shell state snapshots |
| experimental | false | Remote model support |
Enable/disable features with
--enable and --disable:
codex exec --enable web_search_request "research task" codex exec --disable parallel "run sequentially"
JSONL Output (--json
) (v0.71.0+)
--jsonStream events as JSONL for programmatic processing:
codex exec --json "task" > events.jsonl
Save Last Message (-o/--output-last-message
) (v0.71.0+)
-o/--output-last-messageWrite the final agent message to a file:
codex exec -o result.txt "generate summary"
When to Use GPT-5.2-Codex vs GPT-5.2
GPT-5.2-Codex (for code-related tasks):
- Implementation, refactoring, code analysis
- Debugging, fixing bugs, optimization
- Any task involving code understanding
Read-only (default):
codex exec -m gpt-5.2-codex -s read-only -c model_reasoning_effort=xhigh "analyze code"
Workspace-write (only when user explicitly requests editing):
codex exec -m gpt-5.2-codex -s workspace-write -c model_reasoning_effort=xhigh "edit this file"
GPT-5.2 (for general tasks):
- Architecture and system design
- Explanations, documentation, reviews
- Planning, strategy, general reasoning
Read-only (default):
codex exec -m gpt-5.2 -s read-only -c model_reasoning_effort=xhigh "design architecture"
Workspace-write (only when user explicitly requests editing):
codex exec -m gpt-5.2 -s workspace-write -c model_reasoning_effort=xhigh "update the README"
Fallback Models (Backward Compatibility)
Use GPT-5.1-Codex-Max When:
- GPT-5.2-codex is unavailable
- Explicit requirement for the older codex model
Use GPT-5.1 When:
- GPT-5.2 is unavailable
- Explicit requirement for the older general model
Default: Use
gpt-5.2-codex for coding tasks and gpt-5.2 for reasoning tasks. Fall back to GPT-5.1 variants only if primary models are unavailable.
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.71.0)
Windows Sandbox Support
Windows sandbox is available for filesystem and network access control.
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 models (gpt-5.2, gpt-5.1-codex-max, gpt-5.1-codex) support verbosity override via
-c model_verbosity=<level> for controlling output detail levels.
Local/OSS Model Support
Use
--oss with --local-provider to use local LLM providers:
codex exec --oss --local-provider ollama "task" codex exec --oss --local-provider lmstudio "task"
Pattern References
For command construction examples and workflow patterns, Claude can reference:
- Common codex exec usage patternsreferences/command-patterns.md
- Session continuation and resume workflowsreferences/session-workflows.md
- Complex configuration and flag combinationsreferences/advanced-patterns.md
These files provide detailed examples for constructing valid codex exec commands for various scenarios.
Additional Resources
For more details, see:
- Codex CLI command referencereferences/codex-help.md
- Full configuration optionsreferences/codex-config.md
- Installation and quick start guideREADME.md