name: codex-delegator
description: Automatically delegate complex, logic-intensive tasks to OpenAI Codex CLI via codex exec --full-auto. Claude Code uses this skill to invoke Codex for complex backend logic, intricate algorithms, or persistent bugs. Enables seamless AI-to-AI collaboration where Claude Code analyzes and Codex executes.

Codex Delegator

Overview

This skill enables Claude Code to automatically delegate complex, challenging tasks to OpenAI Codex CLI using codex exec --full-auto. When Claude Code encounters tasks that require different problem-solving approaches, deep logical analysis, or tasks that have proven resistant to repeated attempts, it can seamlessly invoke Codex to provide fresh perspectives and alternative solutions. The delegation happens automatically and transparently, with Claude Code handling context preparation, execution, and solution validation.

How Automated Delegation Works

When Claude Code determines a task is suitable for delegation:

1. Analysis Phase: Claude Code analyzes the task complexity, context, and requirements
2. Decision: Determines if delegation would be beneficial based on:
3. Task has been attempted 2+ times without success
4. High logic complexity (nested conditions, complex algorithms)
5. Backend/algorithm intensive work

6. Need for different problem-solving approach

7. Delegation: Automatically invokes Codex:
   ```bash
   codex exec --full-auto "detailed task context with:

8. Problem description
9. Architecture and constraints
10. Previous attempts and failures

11. Success criteria"
    ```

12. Validation: Claude Code reviews Codex's solution for correctness and completeness

13. Integration: Returns validated solution to user with transparency about using Codex

User Transparency: Claude Code will inform you when it delegates to Codex, e.g., "I'm using Codex to generate this complex backend logic..."

When to Use This Skill

Activate this skill specifically for:

1. Complex Backend Logic
2. Intricate business logic implementations
3. Complex data processing pipelines
4. Sophisticated algorithm implementations
5. Multi-layered service architectures

6. Advanced state management systems

7. Logic-Intensive Problems

8. Complex conditional logic with many edge cases
9. Intricate data transformations
10. Complex query optimization
11. Advanced caching strategies

12. Sophisticated error handling flows

13. Persistent Unsolved Problems

14. Bugs that remain after multiple fix attempts
15. Performance issues that resist optimization
16. Race conditions and concurrency problems
17. Memory leaks that are hard to track

18. Integration issues between complex systems

19. When Different Perspective Needed

20. Tasks attempted multiple times without success
21. Problems requiring alternative approaches
22. Situations where fresh analysis would help
23. Complex refactoring that's gotten stuck

DO NOT Use This Skill For

• Simple CRUD operations
• Basic UI components
• Straightforward bug fixes
• Simple configuration changes
• General coding questions or tutorials

Quick Decision Framework

Use Codex when:
- ✅ Problem has been attempted 2+ times without resolution
- ✅ Logic complexity score is high (multiple nested conditions, complex state)
- ✅ Backend/algorithm heavy task
- ✅ Need different problem-solving approach

Don't use Codex when:
- ❌ Problem is straightforward
- ❌ First attempt at the problem
- ❌ Simple frontend/styling work
- ❌ Basic setup or configuration

Delegation Workflow

Step 1: Verify Installation

Before delegating, check if Codex is available:

which codex

If not installed:

npm i -g @openai/codex
codex auth

Step 2: Prepare Task Context

Create clear, detailed task description including:

1. Problem statement - What needs to be solved
2. Context - Relevant code, architecture, constraints
3. Attempts made - What has been tried and why it failed
4. Expected outcome - Clear success criteria
5. Key files - Specific files that need attention

Step 3: Choose Execution Strategy

Strategy A: Interactive Mode (Recommended for Complex Problems)

Use when problem requires exploration and iteration:

cd /path/to/project
codex

Then provide detailed context:

I need help with [problem description].

Context:
- [Architecture overview]
- [Relevant constraints]
- [Previous attempts and failures]

The issue is in these files:
- [file1]: [specific problem]
- [file2]: [specific problem]

Goal: [clear success criteria]

Advantages:
- Can iterate on the solution
- Review changes with /diff
- Undo mistakes with /undo
- Switch models/reasoning levels with /model

Strategy B: Exec Mode (For Well-Defined Problems)

Use when problem is clear and specific:

codex exec "detailed task description with full context"

Add flags as needed:
- --search - For problems requiring up-to-date library knowledge
- --full-auto - For trusted, well-scoped tasks

Strategy C: Cloud Mode (For Persistent Problems)

Use for problems needing multiple solution attempts:

codex cloud exec --env ENV_ID --attempts 3 "complex problem description"

Advantages:
- Multiple solution attempts (best-of-N)
- Asynchronous execution
- Good for trial-and-error scenarios

Step 4: Monitor and Validate

In interactive mode:
- Use /diff to review changes before accepting
- Use /undo if approach is wrong
- Use /review to get Codex's own code review

After execution:
- Run tests to verify solution
- Check edge cases
- Validate performance improvements
- Document the solution approach

Step 5: Resume or Pivot

If problem persists:

# Resume previous session
codex resume

# Or try different model/reasoning level
codex
/model  # Switch to different model or higher reasoning

Effective Task Delegation Examples

Example 1: Complex Backend Logic

Scenario: Implementing sophisticated multi-tenant data isolation with complex permission rules.

cd /path/to/project
codex

I need to implement row-level security for a multi-tenant application.

Requirements:
- Each tenant can only access their own data
- Admin users can access all tenants
- Super admins can impersonate any user
- Audit all data access

Current architecture:
- PostgreSQL database
- Node.js/Express backend
- Using Sequelize ORM

Files involved:
- src/middleware/tenancy.js
- src/models/User.js
- src/policies/access-control.js

Previous attempts:
1. Tried global Sequelize scopes - leaked data in JOIN queries
2. Tried middleware checks - inconsistent across endpoints
3. Current approach using hooks - performance issues

Goal: Bulletproof tenant isolation with good performance

Example 2: Persistent Bug

Scenario: Race condition causing intermittent failures.

codex exec --search "Debug and fix race condition in payment processing:

Context:
- Stripe webhook handler in src/webhooks/stripe.js
- Order service in src/services/orders.js
- Redis cache for order status

Problem:
- 5% of payments succeed but orders stay in 'pending' state
- Happens only under high load
- Attempted fixes:
  1. Added database transaction - didn't help
  2. Increased Redis TTL - still fails
  3. Added retry logic - made it worse

Stack trace (intermittent):
[paste stack trace]

Need: Root cause analysis and fix with proper synchronization"

Example 3: Complex Algorithm

Scenario: Optimizing complex matching algorithm.

cd /path/to/project
codex

Need to optimize recommendation engine in src/algorithms/matching.js

Current implementation:
- O(n²) complexity with nested loops
- Processes 10k items in 30 seconds (too slow)
- Need to handle 100k+ items

Constraints:
- Must maintain ranking accuracy
- Memory limit: 2GB
- Real-time updates required

Attempted optimizations:
1. Added caching - helped but not enough
2. Tried batch processing - broke real-time requirement
3. Implemented early termination - minimal impact

Goal: Sub-second processing for 100k items

Advanced Techniques

Using Enhanced Reasoning

For extremely complex problems, request higher reasoning effort:

codex
/model  # Choose GPT-5 or increase reasoning level

Then provide the complex problem.

Configuring AGENTS.md for Complex Tasks

Create project-specific guidelines:

codex
/init

Edit AGENTS.md to include:
- Architecture constraints
- Code style requirements
- Testing requirements
- Performance benchmarks
- Security considerations

Leveraging MCP for Enhanced Context

Add relevant MCP servers for domain-specific knowledge:

codex mcp add <database-schema-server>
codex mcp add <api-documentation-server>

Multi-Attempt Strategy

For very difficult problems:

# Try 4 different approaches
codex cloud exec --env ENV_ID --attempts 4 "complex problem"

When to Resume vs Start Fresh

Resume session when:
- Continuing work on same problem
- Codex needs more context from discussion
- Iterating on partial solution

Start fresh when:
- Previous approach was completely wrong
- Need different perspective
- Session has gotten too long/confused

Validating Solutions

After Codex provides solution:

1. Code Review
   bash # In Codex interactive mode /review

2. Run Tests
   bash npm test # or appropriate test command

3. Performance Testing

4. Benchmark critical paths
5. Load testing for backend changes

6. Profile memory usage

7. Security Review

8. Check for injection vulnerabilities
9. Validate input sanitization
10. Review authentication/authorization

Troubleshooting Task Delegation

Codex Produces Incomplete Solution

1. Provide more specific context
2. Break problem into smaller sub-tasks
3. Use interactive mode instead of exec mode
4. Switch to higher reasoning model

Solution Doesn't Work

1. Use /undo to rollback
2. Provide error messages and stack traces
3. Clarify constraints and requirements
4. Try /review to get Codex to check its own work

Codex Misunderstands Requirements

1. Resume session and clarify
2. Provide concrete examples
3. Show what NOT to do
4. Reference specific code patterns to follow

Integration with Claude Code Workflow

This skill enables seamless AI-to-AI collaboration:

Automated Workflow

1. User Request: "Fix this race condition bug that I've been trying to solve for hours"
2. Claude Code Analysis: Recognizes this fits delegation criteria (persistent problem, complex)
3. Automatic Delegation:
   bash codex exec --full-auto "Debug race condition in payment processing: [Full context from previous attempts] [Architecture details] [Attempted fixes and why they failed]"
4. Codex Execution: Analyzes, generates solution, applies fix
5. Claude Code Validation: Reviews solution, runs tests, checks integration
6. User Response: "I've used Codex to fix the race condition. The issue was... [explanation]"

Manual Workflow (Still Supported)

Users can also manually invoke Codex following the guidance in this skill for more control over the delegation process.

Cost and Performance Considerations

Codex is cost-effective for:
- Complex problems requiring deep analysis
- Tasks needing multiple solution attempts
- Problems that would take many iterations

Use Claude Code instead for:
- First attempts at problems
- Straightforward implementations
- Simple bug fixes

Resources

Reference Documentation

See references/execution_strategies.md for:
- Detailed command syntax
- Complex task template examples
- Troubleshooting patterns
- Performance optimization techniques

Load this reference when detailed command syntax or advanced patterns are needed.

Quick Reference Commands

# Installation
npm i -g @openai/codex
codex auth

# Interactive mode (most common for complex tasks)
cd /path/to/project
codex

# Exec mode with context
codex exec "detailed task with full context"

# Multi-attempt for difficult problems
codex cloud exec --env ENV_ID --attempts 3 "complex task"

# Resume previous session
codex resume

# Key slash commands in interactive mode
/model      # Switch models/reasoning
/diff       # Review changes
/undo       # Rollback
/review     # Code review

External Resources

• Official documentation: https://developers.openai.com/codex/cli/
• GitHub repository: https://github.com/openai/codex
• Command reference: https://developers.openai.com/codex/cli/reference/

Success Metrics

Track when delegation is effective:

✅ Success indicators:
- Problem solved after delegation
- Solution more elegant than previous attempts
- Performance improvements achieved
- Bug fixed permanently

❌ Failure indicators:
- Problem still unsolved
- Solution too complex
- Introduced new bugs
- Didn't understand requirements

Adjust delegation strategy based on these outcomes.