---
name: codex-builder
description: "Execute implementation plans by delegating to Codex CLI for autonomous code implementation. Use when: (1) User has a plan file generated by Claude Code's plan mode and wants to implement it, (2) User explicitly requests Codex to implement a plan, (3) After plan review is complete and ready for implementation, (4) User provides a path to a plan markdown file and wants automatic implementation. The skill reads the plan file and delegates full implementation to Codex."
---

# 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:
```markdown
## 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
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

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

## 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:
   ```bash
   git add -A && git commit -m "Before codex implementation"
   ```

6. **Review changes after**: After Codex completes, review all changes:
   ```bash
   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:

```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
```

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