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:

Execute Codex with the plan
Report progress and completion status
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

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.
Review the plan first: Before executing, read the plan carefully. Make sure the approach is sound and file paths are correct.
Start with smaller plans: For your first use, try a plan with 2-3 simple steps to understand how Codex Builder works.
Check working directory: Ensure the cwd in the plan frontmatter or --cwd flag points to the correct repository root.
Backup your code: Codex will modify files. Use git to commit your current state first:
```
git add -A && git commit -m "Before codex implementation"
```
Review changes after: After Codex completes, review all changes:
```
git diff
git status
```
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
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