How to Use Codex Builder from Other Agents

Codex Builder is a specialized tool that takes implementation plans (generated by Claude Code's plan mode or claude-planner skill) and delegates the actual implementation to Codex CLI. When you have a detailed plan and want Codex to autonomously implement it, use this skill.

⚠️ Important: Execution Time Notice

Codex Builder typically takes 5-20 minutes to complete, depending on plan complexity, number of files, and implementation scope. During execution:

• The terminal may appear frozen with no output - this is normal
• Do NOT interrupt or terminate the process
• Codex is actively working in the background, reading files, writing code, and implementing the plan
• Use --verbose flag to see real-time progress if you need reassurance
• Be patient - autonomous implementation requires time for careful coding and testing
• Larger plans (10+ steps) may take 15-20 minutes or more

If you interrupt the process thinking it's stuck, you'll lose all progress and may end up with partially-implemented changes.

When to Use Codex Builder

• You have a plan file (markdown) from Claude Code's plan mode
• Plan has been reviewed and approved, ready for implementation
• You want autonomous implementation without manual step-by-step guidance
• The plan contains clear implementation steps with file paths and actions
• You prefer Codex's implementation approach for the specific task

The File-Based Pattern

Codex Builder works with a simple input/output pattern:

Step 1: Locate Your Plan File

Plan files are typically saved by Claude Code in:

• Plan mode default location: ~/.claude/plans/random-string.md
• claude-planner skill output: /tmp/claude-plan-YYYYMMDD-HHMMSS.md
• Custom location if you specified -o flag

Example plan file structure:

## Plan
Add user authentication with JWT tokens...

## Overview
This plan outlines the steps to add user authentication with JWT tokens to the application.

## Files to Modify/Create
- src/middleware/auth.ts — Create auth middleware
- src/routes/api.ts — Add protected routes

## Implementation Steps
1. src/middleware/auth.ts — Create JWT validation middleware
2. src/routes/api.ts — Apply middleware to protected routes
...

Step 2: Invoke Codex Builder

Use the provided script with the plan file path:

bash skills/codex-builder/scripts/execute-plan.sh <plan-file-path>

⏱️ Expected wait time: 5-20 minutes - The terminal will appear inactive while Codex implements your plan. This is normal. Add --verbose to see progress.

Flags:

• First argument: Path to the plan markdown file (required)
• -o <path>: Output file for implementation report (default: /tmp/codex-build-report-YYYYMMDD-HHMMSS.txt)
• --cwd <path>: Working directory for implementation (default: extracted from plan frontmatter or current directory)
• -m, --model <name>: Codex model to use (default: from ~/.codex/config.toml)
• --verbose: Show Codex's progress output (recommended for first-time users to see that it's working)

Step 3: Review Implementation Results

The script will:

1. Execute Codex with the plan
2. Report progress and completion status
3. Save implementation report to specified output file

# Read the implementation report
Read /tmp/codex-build-report.txt

The report includes:

• Which steps were completed
• Files that were created/modified
• Any issues encountered
• Suggested next steps (testing, verification)

Example Session

# 1. Generate plan using claude-planner
bash skills/claude-planner/scripts/plan.sh /tmp/auth-request.txt -o /tmp/auth-plan.md

# 2. Review the plan
Read /tmp/auth-plan.md
# Plan looks good, ready to implement

# 3. Execute with Codex Builder (using specific model)
bash skills/codex-builder/scripts/execute-plan.sh /tmp/auth-plan.md -o /tmp/auth-build.txt --model gpt-5.2-codex

# 4. Review implementation
Read /tmp/auth-build.txt
# Codex completed 5/5 steps successfully
# Files created: src/middleware/auth.ts, src/types/auth.d.ts
# Files modified: src/routes/api.ts, src/server.ts
# Next steps: Run tests, verify authentication flow

# 5. Verify the implementation
# Run tests, check files, etc.

Tips

1. Be patient with execution time: Codex Builder takes several minutes to complete, often 5-20 minutes for complex plans. The terminal will look frozen - this is expected behavior. For peace of mind, use --verbose flag to see real-time progress. Do not interrupt the process.
2. Review the plan first: Before executing, read the plan carefully. Make sure the approach is sound and file paths are correct.
3. Start with smaller plans: For your first use, try a plan with 2-3 simple steps to understand how Codex Builder works.
4. Check working directory: Ensure the cwd in the plan frontmatter or --cwd flag points to the correct repository root.
5. Backup your code: Codex will modify files. Use git to commit your current state first:

   git add -A && git commit -m "Before codex implementation"

6. Review changes after: After Codex completes, review all changes:

   git diff
   git status

7. Iterate if needed: If Codex doesn't complete some steps, you can:
   • Fix issues manually
   • Refine the plan and run again
   • Create a follow-up plan for remaining work
8. Plan quality matters: Better plans with clear steps, specific file paths, and detailed actions produce better implementations.

Common Issues

"Terminal appears frozen/stuck": This is NORMAL. Implementation takes 5-20 minutes depending on plan size. Codex is working in the background. Do NOT interrupt. Use --verbose flag to see progress if concerned.

"Plan file not found": Check the path is correct and the file exists

"Invalid plan format": Ensure the plan has proper markdown structure with required sections (Summary, Files to Modify/Create, Implementation Steps)

"Working directory not found": Verify the cwd in plan frontmatter or provide correct --cwd flag

Incomplete implementation: Codex may struggle with:

• Vague or ambiguous steps
• Missing context about existing code patterns
• Complex steps that need breaking down
• Missing dependencies or setup

Merge conflicts: If files were modified since plan creation:

• Review git diff carefully
• Consider regenerating the plan with current code state
• Manually merge if conflicts are minor

Process seems to take too long: Large plans (10+ steps) or complex implementations can take 15-20 minutes. If it exceeds 30 minutes with --verbose showing no progress, then you may interrupt and review partial implementation.

Integration with claude-planner

This skill works seamlessly with claude-planner:

# 1. Create plan with claude-planner
echo "Add Redis caching to API" | \
  bash skills/claude-planner/scripts/plan.sh - -o /tmp/redis-plan.md

# 2. Implement with codex-builder
bash skills/codex-builder/scripts/execute-plan.sh /tmp/redis-plan.md

# Complete workflow: planning → implementation in two commands

What Codex Builder Does

Codex Builder:

• ✓ Reads the plan file and extracts implementation steps
• ✓ Sets up proper working directory context
• ✓ Invokes Codex CLI with full autonomy to implement
• ✓ Creates and modifies files according to the plan
• ✓ Reports completion status and any issues
• ✓ Generates an implementation report

Codex Builder does NOT:

• ✗ Modify or validate the plan (use claude-planner for that)
• ✗ Run tests automatically (you should verify after)
• ✗ Commit changes to git (you review and commit)
• ✗ Handle deployment or production concerns

Safety Notes

• Always review the plan before implementation
• Use version control - commit before running
• Review all changes after Codex completes
• Test thoroughly - Codex may introduce bugs
• Start small - try simple plans first to build confidence