gh-lucklyric-cc-dev-tools-plugins-codex/skills/codex/SKILL.md

name, version, description

name	version	description
codex	1.4.0	Invoke Codex CLI for complex coding tasks requiring high reasoning capabilities. This skill should be invoked when users explicitly mention "Codex", request complex implementation challenges, advanced reasoning, or need high-reasoning model assistance. Automatically triggers on codex-related requests and supports session continuation for iterative development.

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.1 "prompt" (CORRECT)
• codex -m gpt-5.1 "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.1 (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.1-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.1 -s read-only \
  -c model_reasoning_effort=high \
  --enable web_search_request \
  "<user's prompt>"

For Code Editing Tasks

codex exec -m gpt-5.1-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.1 (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.1-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.1-codex (standard model) is still available and works identically. Use gpt-5.1-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.1	-m gpt-5.1	General reasoning tasks
Model (code editing)	gpt-5.1-codex-max	-m gpt-5.1-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.1-codex-max support)

Flag	Values	Description
-m, --model	gpt-5.1, gpt-5.1-codex, gpt-5.1-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.1-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.1 model family:

• gpt-5.1 - General reasoning, architecture, reviews (default)
• gpt-5.1-codex-max - Code editing and implementation (default for code tasks)
• gpt-5.1-codex - Standard code editing (available for backward compatibility)

Performance Characteristics:

• gpt-5.1-codex-max is 27-42% faster than gpt-5.1-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.1
• Code editing tasks → gpt-5.1-codex-max (recommended for best performance)
• Backward compatibility → gpt-5.1-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.1' for general reasoning or 'gpt-5.1-codex-max' for code editing (gpt-5.1-codex also available for backward compatibility)

Example: codex exec -m gpt-5.1 "your prompt here"
Example: codex exec -m gpt-5.1-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.1 -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.1-codex-max -s workspace-write \
  -c model_reasoning_effort=high \
  "Edit this file to implement the BST insert method"

Result: Codex uses gpt-5.1-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.1-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.1-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.1 vs GPT-5.1-Codex-Max

Use GPT-5.1 (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.1-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.1-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.1 for general tasks. Use gpt-5.1-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.1-codex-max, gpt-5.1-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