codex-builder

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.

• 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

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:

```markdown

Add user authentication with JWT tokens...

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

• src/middleware/auth.ts — Create auth middleware
• src/routes/api.ts — Add protected routes

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

bash skills/codex-builder/scripts/execute-plan.sh

```

⏱️ 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 : Output file for implementation report (default: /tmp/codex-build-report-YYYYMMDD-HHMMSS.txt)
• --cwd : Working directory for implementation (default: extracted from plan frontmatter or current directory)
• -m, --model : 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

```bash

# 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)

```

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

```

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.

1. Review the plan first: Before executing, read the plan carefully. Make sure the approach is sound and file paths are correct.

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

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

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

```bash

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

```

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

```bash

git diff

git status

```

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

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

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

This skill works seamlessly with claude-planner:

```bash

# 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

```

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

• 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