codex-implement

name	codex-implement
description	Use when delegating code implementation to Codex CLI with Claude-managed decomposition, context scoping, and verification.
argument-hint	[SPEC_FILE | "description"] [--consult] [--no-commit] [--dry-run] [--batch] [--model MODEL]
allowed-tools	Bash, Read, Write, Edit, Glob, Grep, Agent, AskUserQuestion

Codex Implement

Delegate bounded implementation tasks to OpenAI Codex CLI. Claude acts as Architect (decomposes, selects context, verifies); Codex acts as Editor (implements each bounded task).

When to Use

• Ad-hoc implementation: "have Codex build this"
• Cross-model implementation for blind-spot coverage
• When you want Claude to orchestrate and verify, not write the code itself

Arguments

• Positional: Spec file path OR quoted text description (optional)
• --consult — Run /codex-consult on the implementation plan before executing
• --no-commit — Skip commits after each task (leave changes unstaged)
• --dry-run — Show Implementation Brief + task decomposition without executing
• --model MODEL — Override Codex model for this invocation
• --batch — Non-interactive mode for automated pipelines (skip user confirmations). Used by /phase-start --codex to drive tasks without pausing for approval

Workflow

Copy this checklist and track progress:

Implementation Progress:
- [ ] Phase 1: Pre-flight checks
- [ ] Phase 2: Gather input
- [ ] Phase 3: Analyze and decompose
- [ ] Phase 4: Optional consultation (if --consult)
- [ ] Phase 5: Execute tasks
- [ ] Phase 6: Summary

Phase 1: Pre-flight

Guard Checks

# Already inside Codex?
if [ -n "$CODEX_SANDBOX" ]; then
  echo "Already running inside Codex. Skipping."
  exit 0
fi

# Codex CLI installed?
codex --version

# Authenticated?
codex login status

If Codex CLI is not available or not authenticated, report the error and STOP:

ERROR: Codex CLI required
==========================
Install: npm install -g @openai/codex
Auth:    codex login

Load Configuration

Read .claude/settings.local.json:

CODEX_MODEL=$(jq -r '.codexImplement.model // .codexReview.codeModel // empty' .claude/settings.local.json 2>/dev/null)
CODEX_EFFORT=$(jq -r '.codexImplement.effort // .codexReview.effort // empty' .claude/settings.local.json 2>/dev/null)
TIMEOUT_MINS=$(jq -r '.codexImplement.timeoutMinutes // .codexReview.taskTimeoutMinutes // 60' .claude/settings.local.json 2>/dev/null || echo "60")
MAX_TASKS=$(jq -r '.codexImplement.maxTasks // 5' .claude/settings.local.json 2>/dev/null || echo "5")
ENABLED=$(jq -r '.codexImplement.enabled // true' .claude/settings.local.json 2>/dev/null || echo "true")

If --model flag provided, override CODEX_MODEL. If enabled is false, report and STOP.

Parse Flags

Extract from argument string:

• --consult → CONSULT=true
• --no-commit → NO_COMMIT=true
• --dry-run → DRY_RUN=true
• --batch → BATCH=true
• --model VALUE → override CODEX_MODEL
• Remaining text → INPUT (file path or description)

Phase 2: Gather Input

Determine input mode from INPUT:

Mode A: Spec File

If INPUT is a file path that exists:

1. Read the file
2. Extract: problem statement, requirements, acceptance criteria, scope boundaries
3. If BATCH is false: Present summary to user via AskUserQuestion: "This is what I'll have Codex implement. Correct?"
4. If user modifies, incorporate changes

Mode B: Inline Text

If INPUT is quoted text (not a file path):

1. Claude explores the codebase to understand the affected area:
   • Glob for relevant files
   • Read key files to understand patterns
   • Identify what exists vs. what needs to be built
2. Generate an Implementation Brief (internal, not written to disk):
   • What to build (from user's description)
   • Affected files (from codebase exploration)
   • Success criteria (Claude generates testable criteria)
   • Constraints (from AGENTS.md and codebase conventions)
3. If BATCH is false: Present brief to user via AskUserQuestion for confirmation

Mode C: Interactive

If BATCH is true and no INPUT provided: STOP with error — batch mode requires a spec file or description.

If no INPUT provided (and BATCH is false):

1. Ask one question at a time via AskUserQuestion (conversational, discover-style)
2. Follow threads: if an answer raises something interesting, explore it
3. Smart-skip: don't ask what's already clear from context
4. Typical questions:
   • "What would you like Codex to build?"
   • "Where in the codebase should this live?" (after exploring to suggest options)
   • "Any constraints or patterns it should follow?"
   • "How should we verify it works?"
5. Escape hatch: if user says "just do it", ask one final critical question then proceed
6. Move on when sufficient clarity achieved (typically 3-5 questions)
7. Build Implementation Brief from answers (same structure as Mode B)

Implementation Brief Structure

All modes produce this internal structure:

IMPLEMENTATION BRIEF
====================
Description: {what to build}
Affected files: {list of files Codex should read/modify}
Success criteria:
  1. {testable criterion}
  2. {testable criterion}
Constraints:
  - {from AGENTS.md}
  - {from codebase conventions}

Phase 3: Analyze and Decompose

See DECOMPOSITION.md for the full decision tree.

Claude reads the Implementation Brief and decides single vs. multi-task:

Single task if ALL of:

• Touches ≤ 3 files
• Single concern (one logical change)
• Estimated ≤ ~80 lines of change
• No cross-cutting concerns

Multiple tasks if ANY of:

• Touches > 3 files
• Multiple concerns
• Cross-cutting layers (API + frontend + database)
• Estimated > 80 lines

Decomposition Rules

• Each task: single bounded concern
• Order by dependency (foundational first)
• Cap at MAX_TASKS (default 5)
• If exceeds cap: warn and suggest full /feature-spec → /feature-plan workflow, but allow override if user confirms

User Confirmation

Present the task list to the user:

IMPLEMENTATION PLAN
===================
Tasks: {N}

1. {task description} — touches {files}
2. {task description} — touches {files}
...

Estimated Codex time: ~{N * timeout/4} minutes (worst case: {N * timeout} minutes)

If BATCH is false, ask: "Ready to execute?" with options:

• "Execute (Recommended)"
• "Modify tasks"
• "Cancel"

If BATCH is true, proceed directly to execution.

Dry Run Exit

If --dry-run: display the Implementation Brief and task list, then STOP.

Phase 4: Optional Consultation

If --consult flag is set:

1. Write Implementation Brief to temp file
2. Invoke /codex-consult on the temp file
3. Present Codex's findings to user
4. If BATCH is false: Ask: "Incorporate suggestions?" → refine brief if yes
5. If BATCH is true: Auto-incorporate non-breaking suggestions, skip interactive refinement
6. Clean up temp file
7. Proceed to Phase 5

Phase 5: Execute Tasks

Safety Guard Pattern

Apply this pattern before and after every Codex invocation to prevent accidental commits from persisting:

# Before invocation — fail fast on dirty worktree, record HEAD
if [ -n "$(git status --porcelain)" ]; then
  echo "WARNING: Worktree has uncommitted changes. Commit or stash before running Codex."
fi
HEAD_BEFORE=$(git rev-parse HEAD)

# ... invoke Codex ...

# After invocation — revert any commits Codex made
HEAD_AFTER=$(git rev-parse HEAD)
if [ "$HEAD_BEFORE" != "$HEAD_AFTER" ]; then
  echo "WARNING: Codex made commits. Reverting."
  git reset --soft "$HEAD_BEFORE"
  git restore --staged .
fi

For each task (sequentially):

Step 1: Capture Safety State

Apply the safety guard pattern (pre-invocation half) defined above.

Step 2: Build Task Prompt

See PROMPT_TEMPLATE.md for the full template.

Write prompt to temp file. Include:

• AGENTS.md or CLAUDE.md context, if present
• ONLY files relevant to this specific task (not all affected files)
• Success criteria for THIS task only
• Constraints: follow patterns, don't commit, stay in scope

Step 3: Invoke Codex

# Build model flag
MODEL_FLAG=""
if [ -n "$CODEX_MODEL" ]; then
  MODEL_FLAG="--model $CODEX_MODEL"
fi

# Build effort flag
EFFORT_ARGS=()
if [ -n "$CODEX_EFFORT" ]; then
  EFFORT_ARGS=(-c "model_reasoning_effort=\"$CODEX_EFFORT\"")
fi

PROMPT_FILE="/tmp/codex-impl-task-${TASK_NUM}.md"
OUTPUT_FILE="/tmp/codex-impl-task-${TASK_NUM}-output.txt"

cat $PROMPT_FILE | codex exec \
  --sandbox danger-full-access \
  -c 'approval_policy="never"' \
  -c 'features.search=true' \
  $MODEL_FLAG \
  "${EFFORT_ARGS[@]}" \
  -o $OUTPUT_FILE \
  -
EXIT_CODE=$?

Use Bash tool timeout parameter: TIMEOUT_MINS * 60 * 1000 milliseconds.

MANDATORY rules:

• NEVER use run_in_background
• NEVER retry with modified syntax
• NEVER use 2>&1 (corrupts output parsing)
• Use Bash tool timeout, not shell timeout

Step 4: Safety Check

Apply the safety guard pattern (post-invocation half) defined above.

Step 5: Parse Result

if [ $EXIT_CODE -eq 124 ]; then
  STATUS="FAILED"; ISSUE="Timeout after ${TIMEOUT_MINS} minutes"
elif [ $EXIT_CODE -ne 0 ]; then
  STATUS="FAILED"; ISSUE="Codex exited with code $EXIT_CODE"
elif [ ! -f "$OUTPUT_FILE" ]; then
  STATUS="FAILED"; ISSUE="No output file produced"
else
  STATUS=$(grep "^Status:" "$OUTPUT_FILE" | head -1 | awk '{print $2}')
  if [ -z "$STATUS" ]; then
    STATUS=$(grep "Status:" "$OUTPUT_FILE" | head -1 | awk '{print $2}')
  fi
  if [ -z "$STATUS" ]; then
    STATUS="FAILED"; ISSUE="Could not parse task result"
  fi
fi

Step 6: Verify

See VERIFICATION.md for the full verification strategy.

4-tier verification:

1. Scope guard: git diff --name-only — did Codex only touch expected files?
2. Automated checks: Run tests/lint/typecheck if configured
3. Claude review: Read git diff, compare against success criteria
4. Cross-model review (only with --consult): Run /codex-review on the changes

Step 7: Commit or Rollback

On success (unless --no-commit):

• Stage changed files: git add {specific files}
• Commit: impl: {task description} [codex-implement]

On failure:

• Show what went wrong (Codex output + verification results)
• If BATCH is true: report failure status and return immediately (let the caller handle retry/skip/abort decisions)
• If BATCH is false: Ask user via AskUserQuestion:
  • "Retry this task"
  • "Skip and continue"
  • "Abort remaining tasks"
  • "I'll implement this one manually"
• After 2 consecutive failures on same task: recommend manual implementation

Step 8: Clean Up

rm -f $PROMPT_FILE $OUTPUT_FILE

Phase 6: Summary

Batch Mode Result Block

Result Contract

When BATCH is true, output this structured result block as the final output so callers can parse status:

CODEX_IMPLEMENT_RESULT
======================
Status: COMPLETE | PARTIAL | FAILED
Tasks: {completed}/{total}
Files changed: {list of changed file paths}
Issue: {description, only if PARTIAL or FAILED}

• COMPLETE — all tasks succeeded and passed verification
• PARTIAL — some tasks succeeded, others failed/skipped
• FAILED — no tasks succeeded or critical pre-flight failure

Interactive Mode Summary

When BATCH is false, show the full summary:

IMPLEMENTATION COMPLETE
=======================
Tasks: {completed}/{total}
Files created: {count}
Files modified: {count}
Commits: {count}

Changes:
  {commit message 1}
  {commit message 2}
  ...

Next steps:
  - Run full test suite: {test command}
  - Review changes: git diff HEAD~{N}

If any tasks failed or were skipped, include them in the summary with recommendations.

Error Handling

Situation	Action
Codex CLI not installed	Report, suggest install command, STOP
Codex not authenticated	Report, suggest codex login, STOP
Codex times out	Show partial output if available, ask user
Output unparseable	Show raw output, ask user to review
Scope violation	Warn, ask user to accept or revert
2 consecutive failures	Recommend manual implementation
Exceeds maxTasks	Warn, suggest full workflow, allow override
--dry-run	Show brief + tasks, STOP before execution

Configuration

Add to .claude/settings.local.json:

{
  "codexImplement": {
    "enabled": true,
    "model": "gpt-5.3-codex",
    "effort": "xhigh",
    "timeoutMinutes": 60,
    "maxTasks": 5
  }
}

Fallback chain: codexImplement → codexReview → defaults.

REMINDER: Codex Invocation Rules

These rules are mandatory for every codex exec invocation:

• NEVER use run_in_background — always execute synchronously
• NEVER retry with modified syntax — report exit code and skip
• NEVER use 2>&1 — corrupts output parsing (Codex streams progress to stderr)
• Use Bash tool timeout parameter — not shell timeout command
• Always capture HEAD before and after — revert accidental commits