How to Use Codex Builder from Claude Code

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.

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>

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

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. Review the plan first: Before executing, read the plan carefully. Make sure the approach is sound and file paths are correct.

2. Start with smaller plans: For your first use, try a plan with 2-3 simple steps to understand how Codex Builder works.

3. Check working directory: Ensure the cwd in the plan frontmatter or --cwd flag points to the correct repository root.

4. Backup your code: Codex will modify files. Use git to commit your current state first:

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

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

   git diff
   git status
   

6. 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

7. Plan quality matters: Better plans with clear steps, specific file paths, and detailed actions produce better implementations.

Common Issues

“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

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