Imported from reason-machines/codex-skills (skills/claude-code-codex-delegation/SKILL.md). Install upstream with npx skills add reason-machines/codex-skills --skill claude-code-codex-delegation. Copyright stays with the author.

Claude Code Codex Delegation Skill

Skill by ara.so — Codex Skills collection.

Overview

This skill enables Claude Code to invoke the Codex CLI for automated code analysis, refactoring, and editing workflows. Codex is an autonomous AI coding agent that can perform complex multi-file operations, repository analysis, and sustained editing sessions. By delegating tasks to Codex, you leverage its specialized capabilities for code transformation while maintaining Claude Code's conversational interface.

Installation

Prerequisites

Ensure the codex CLI is installed and configured:

# Verify installation
codex --version

# If not installed, follow Codex documentation to install
# Ensure valid credentials are configured

The codex binary must be available on your PATH.

Installing This Skill

Option 1: Plugin Installation (Recommended)

/plugin marketplace add skills-directory/skill-codex
/plugin install skill-codex@skill-codex

Option 2: Manual Skill Installation

git clone --depth 1 https://github.com/skills-directory/skill-codex.git /tmp/skills-temp
mkdir -p ~/.claude/skills
cp -r /tmp/skills-temp/plugins/skill-codex/skills/codex ~/.claude/skills/codex
rm -rf /tmp/skills-temp

Key Commands

Basic Codex Execution

# Single-shot analysis (read-only sandbox)
codex exec -m gpt-5.3-codex-spark \
  --sandbox read-only \
  --full-auto \
  --skip-git-repo-check \
  "Analyze this repository for security vulnerabilities" 2>/dev/null

# Code editing with write access
codex exec -m gpt-5.4 \
  --config model_reasoning_effort="high" \
  --sandbox writable \
  --full-auto \
  "Refactor all API handlers to use async/await patterns"

# Resume previous session
codex resume <session-id>

Model Selection

Choose based on task complexity:

• gpt-5.5: Most capable, highest cost, best for complex multi-step tasks
• gpt-5.4: Balanced performance for general refactoring
• gpt-5.4-mini: Fast, cost-effective for simple tasks
• gpt-5.3-codex-spark: Optimized for code-specific reasoning
• gpt-5.3-codex: Baseline code model

Reasoning Effort Levels

# Low effort (faster, cheaper)
--config model_reasoning_effort="low"

# Medium effort (balanced)
--config model_reasoning_effort="medium"

# High effort (thorough, slower)
--config model_reasoning_effort="high"

Sandbox Modes

• --sandbox read-only: Analysis tasks, no file modifications
• --sandbox writable: Allow Codex to edit files
• --sandbox full: Unrestricted access (use with caution)

Usage Patterns

Pattern 1: Repository Analysis

# User asks: "Analyze this codebase for architectural issues"

codex exec -m gpt-5.3-codex-spark \
  --config model_reasoning_effort="high" \
  --sandbox read-only \
  --full-auto \
  --skip-git-repo-check \
  "Perform comprehensive architectural analysis. Identify:
   1. Code organization issues
   2. Dependency coupling problems
   3. Testing gaps
   4. Performance bottlenecks
   5. Security concerns
   Provide specific file locations and recommendations." 2>/dev/null

Pattern 2: Automated Refactoring

# User asks: "Refactor this to use TypeScript strict mode"

codex exec -m gpt-5.4 \
  --config model_reasoning_effort="medium" \
  --sandbox writable \
  --full-auto \
  "Enable TypeScript strict mode and fix all resulting type errors:
   1. Update tsconfig.json
   2. Add explicit types to all functions
   3. Fix null/undefined handling
   4. Ensure all tests still pass" 2>/dev/null

Pattern 3: Session Resume

# User asks: "Continue my previous codex session"

# List recent sessions
codex sessions list --limit 10

# Resume specific session
codex resume abc123def456

Pattern 4: Multi-File Migration

# User asks: "Migrate all class components to functional components with hooks"

codex exec -m gpt-5.4 \
  --config model_reasoning_effort="high" \
  --sandbox writable \
  --full-auto \
  "Migrate React class components to functional components:
   1. Convert lifecycle methods to useEffect
   2. Replace this.state with useState
   3. Update event handlers
   4. Preserve all functionality
   5. Update tests accordingly
   
   Process files in src/components directory." 2>/dev/null

Configuration

Environment Variables

# Codex API credentials (if required)
export CODEX_API_KEY="your-api-key-from-env"

# Default model preference
export CODEX_DEFAULT_MODEL="gpt-5.3-codex-spark"

# Default reasoning effort
export CODEX_DEFAULT_EFFORT="medium"

Codex Config File

Codex may use ~/.codex/config.yaml or project-level .codex.yaml:

default_model: gpt-5.3-codex-spark
reasoning_effort: medium
sandbox_mode: read-only
full_auto: true
skip_git_repo_check: true

Thinking Tokens

Important: By default, this skill suppresses Codex's thinking tokens (stderr output) using 2>/dev/null to prevent context window bloat in Claude Code.

To enable thinking tokens for debugging or insight:

# Remove stderr redirect
codex exec -m gpt-5.3-codex-spark \
  --full-auto \
  "Analyze this code"
# Now you'll see Codex's reasoning process

Or explicitly ask Claude: "Show me the thinking tokens from Codex"

Real-World Examples

Example 1: Security Audit

User Prompt: "Use Codex to audit this Express.js API for security issues"

Executed Command:

codex exec -m gpt-5.4 \
  --config model_reasoning_effort="high" \
  --sandbox read-only \
  --full-auto \
  --skip-git-repo-check \
  "Security audit for Express.js API:
   - SQL injection vulnerabilities
   - XSS attack vectors
   - Authentication/authorization flaws
   - Sensitive data exposure
   - Rate limiting gaps
   - CORS misconfigurations
   
   Provide CVE references and fix recommendations." 2>/dev/null

Example 2: Test Generation

User Prompt: "Generate comprehensive tests for all untested modules"

Executed Command:

codex exec -m gpt-5.3-codex-spark \
  --config model_reasoning_effort="medium" \
  --sandbox writable \
  --full-auto \
  "Analyze test coverage and generate missing tests:
   1. Identify modules without tests
   2. Create unit tests for pure functions
   3. Create integration tests for API endpoints
   4. Use existing test framework patterns
   5. Aim for 80%+ coverage
   
   Write tests to __tests__/ directory." 2>/dev/null

Example 3: Dependency Upgrade

User Prompt: "Upgrade all dependencies and fix breaking changes"

Executed Command:

codex exec -m gpt-5.5 \
  --config model_reasoning_effort="high" \
  --sandbox writable \
  --full-auto \
  "Dependency upgrade workflow:
   1. Update package.json to latest compatible versions
   2. Run npm install
   3. Identify breaking changes in CHANGELOG
   4. Update code to match new APIs
   5. Fix all TypeScript errors
   6. Ensure all tests pass
   
   Create git commits for each major dependency." 2>/dev/null

Example 4: Documentation Generation

User Prompt: "Generate API documentation from code"

Executed Command:

codex exec -m gpt-5.3-codex-spark \
  --config model_reasoning_effort="low" \
  --sandbox writable \
  --full-auto \
  "Generate API documentation:
   1. Extract all public API endpoints
   2. Document request/response schemas
   3. Include authentication requirements
   4. Add usage examples
   5. Generate OpenAPI 3.0 spec
   
   Output to docs/api.md and openapi.yaml" 2>/dev/null

Troubleshooting

Codex Command Not Found

# Verify installation
which codex

# Check PATH
echo $PATH

# If missing, reinstall Codex CLI per official docs

Authentication Errors

# Verify credentials
codex auth status

# Re-authenticate if needed
codex auth login

# Check environment variables
env | grep CODEX

Sandbox Permission Errors

If Codex reports permission issues:

# Ensure correct sandbox mode
--sandbox writable  # for file edits

# Check file permissions
ls -la <affected-files>

# For git repositories, ensure .git directory is accessible

Context Window Overflow

If Claude Code runs out of context:

1. Suppress thinking tokens: Ensure 2>/dev/null is present
2. Use targeted prompts: Be specific about which files/modules to analyze
3. Chain operations: Break complex tasks into smaller Codex invocations
4. Use session resume: For multi-turn workflows, use codex resume

Model Timeout or Rate Limits

# Switch to faster model
-m gpt-5.4-mini

# Reduce reasoning effort
--config model_reasoning_effort="low"

# Check Codex status
codex status

Session Not Found

# List available sessions
codex sessions list

# Sessions may expire after 24 hours
# Start new session instead of resuming

Best Practices

1. Start with read-only: Use --sandbox read-only for analysis tasks to prevent unintended modifications
2. Match model to task: Use gpt-5.4-mini for simple tasks, gpt-5.5 for complex refactoring
3. Be specific: Detailed prompts yield better results from Codex
4. Review outputs: Always review Codex-generated code before committing
5. Use version control: Ensure clean git state before allowing write operations
6. Chain thoughtfully: For multi-step workflows, guide Codex through each phase explicitly
7. Monitor costs: Higher-tier models and reasoning efforts consume more tokens

Integration with Claude Code Workflows

Workflow 1: Analysis → Discussion → Action

1. User: "Analyze this codebase with Codex"
2. Claude: [Runs Codex in read-only mode]
3. Claude: [Summarizes findings in conversation]
4. User: "Fix the issues Codex found"
5. Claude: [Runs Codex in writable mode with specific fixes]

Workflow 2: Iterative Refactoring

1. User: "Refactor authentication module"
2. Claude: [Codex session 1 - analyze structure]
3. User: "Good, now apply those changes"
4. Claude: [Codex resume - implement changes]
5. User: "Add tests for the new structure"
6. Claude: [Codex resume - generate tests]

Workflow 3: Validation Pipeline

1. Claude: [Makes code changes directly]
2. User: "Have Codex validate these changes"
3. Claude: [Runs Codex analysis on recent changes]
4. Claude: [Reports validation results]

Advanced Features

Custom Reasoning Configuration

codex exec -m gpt-5.4 \
  --config model_reasoning_effort="high" \
  --config temperature=0.3 \
  --config max_tokens=8000 \
  "Your task here"

Targeting Specific Files

codex exec -m gpt-5.3-codex-spark \
  --files "src/auth/*.ts" \
  --sandbox read-only \
  --full-auto \
  "Analyze authentication implementation in these files"

Combining with Git Operations

# Before refactoring
git checkout -b codex-refactor

# Run Codex
codex exec -m gpt-5.4 --sandbox writable --full-auto "Refactor task"

# After Codex completes
git add .
git commit -m "Codex: automated refactoring"
git diff main

Note: This skill is part of the Codex Skills collection at ara.so. For the most autonomous setup combining Claude Code and Codex, see klaudworks/ralph-meets-rex.