name: dev_invoke_codex-cli description: | Delegate code tasks to OpenAI Codex CLI using markdown file handoff pattern. Write instructions to TASK.md, Codex reads and executes, outputs to OUTPUT.md. Use for implementation, refactoring, code generation requiring extended thinking.

Triggers: codex, codex cli, delegate to codex, codex subagent, implementation task, refactoring task, code generation, gpt-5.2-codex, openai codex, extended thinking, multi-file changes, complex implementation

Prerequisites: Codex CLI authenticated (codex login or OPENAI_API_KEY) Model: gpt-5.2-codex (default, supports xhigh reasoning effort)

Invoking Codex CLI

Delegate tasks to Codex CLI using markdown files for instruction input and deliverable output.

Pattern: Markdown File Handoff

Claude Code                         Codex CLI
    |                                   |
    +-- Write TASK.md ------------------+
    |   (instructions + context)        |
    |                                   |
    +-- Execute: codex e "Read TASK.md, |
    |   follow instructions, write      |
    |   deliverables to OUTPUT.md"      |
    |                                   |
    |                                   +-- Reads TASK.md
    |                                   +-- Executes task
    |                                   +-- Writes OUTPUT.md
    |                                   |
    +-- Read OUTPUT.md <----------------+
    |   (deliverables + results)        |
    v                                   v

Benefits:

• No shell escaping issues (quotes, special characters, code blocks)
• Structured context in reviewable files
• Explicit deliverable format
• Session resume via thread ID

When to Use

• Complex implementation requiring multi-file changes
• Refactoring with dependency tracking
• Code generation with detailed specifications
• Tasks requiring extended thinking (20-30 minutes)

Model Selection

Model: Always use gpt-5.2-codex (latest model)

Reasoning Effort: Adjust based on task complexity

Recommendation: Use default xhigh reasoning for most tasks. Lower reasoning effort for simpler tasks, not older models.

Invocation

Standard Pattern (Recommended)

codex e "Read TASK.md in the current directory. Follow the instructions exactly. Write all deliverables to OUTPUT.md." \
  -C "/path/to/project" \
  --full-auto \
  --skip-git-repo-check

With Lower Reasoning Effort

# For simpler tasks, reduce reasoning effort (not model)
codex e "Read TASK.md, follow instructions, write results to OUTPUT.md" \
  -C "/path/to/project" \
  -c model_reasoning_effort=medium \
  --full-auto \
  --skip-git-repo-check

Resume Session

codex e resume <thread_id> "Read TASK.md for updated instructions, append results to OUTPUT.md"

Core Flags Reference

Model: Always gpt-5.2-codex (latest). Adjust reasoning effort instead of changing models.

Task File Template (TASK.md)

# Task: [Brief Title]

## Objective
[Clear statement of what needs to be accomplished]

## Context
[Relevant background, constraints, requirements]

## Input Files
- `src/api/users.ts` - User service to modify
- `src/types/user.ts` - Type definitions

## Instructions
1. [First step]
2. [Second step]
3. [Third step]

## Deliverables
Write to OUTPUT.md:
- Summary of changes made
- List of files modified
- Any issues encountered
- Recommendations for follow-up
- Thread ID for session resume

## Constraints
- Do not modify files outside src/api/
- Maintain backward compatibility
- Follow existing code style

Output File Template (OUTPUT.md)

Codex should produce:

# Deliverables: [Task Title]

## Summary
[Brief description of what was done]

## Changes Made

### Files Modified
| File | Change |
|------|--------|
| `src/api/users.ts` | Added validation logic |

### Code Changes
[Key code snippets if relevant]

## Issues Encountered
- [Any problems and how resolved]

## Recommendations
- [Suggested follow-up actions]

## Session
Thread ID: `<thread_id>` (for resume)

Workflow Example (ras-commander)

1. Write TASK.md

# Task: Add Validation to Precipitation API

## Objective
Add depth conservation validation to precipitation methods.

## Context
The precipitation methods in ras_commander/precip/ need validation
to ensure depth conservation at 10^-6 precision.

## Input Files
- `ras_commander/precip/Atlas14Storm.py`
- `ras_commander/precip/StormGenerator.py`

## Instructions
1. Add depth conservation check after hyetograph generation
2. Raise ValidationError if conservation fails
3. Log successful validation with actual precision achieved

## Deliverables
Write to OUTPUT.md:
- Summary of validation logic added
- Files modified with line references
- Test cases to validate

## Constraints
- Use existing ValidationSeverity pattern
- Maintain backward compatibility

2. Execute Codex

codex e "Read TASK.md, follow the instructions, write deliverables to OUTPUT.md" \
  -C "C:/GH/ras-commander" \
  --full-auto \
  --skip-git-repo-check

3. Read OUTPUT.md

Parse results, verify changes, continue workflow.

Environment Variables

CODEX_API_KEY=sk-xxx      # Required (or use codex login)
OPENAI_API_KEY=sk-xxx     # Alternative

Session Management

• Thread ID appears in Codex console output at session start
• Request thread ID in OUTPUT.md deliverables section
• Resume with: codex e resume <thread_id> "follow-up instruction"

Tips

1. Be explicit in TASK.md - Include all context, don't assume
2. Specify output structure - Tell Codex exactly what OUTPUT.md should contain
3. List input files - Explicitly name files Codex should read
4. Define constraints - Prevent unwanted modifications
5. Request thread ID - Include in deliverables for session resume
6. Use default model - gpt-5.2-codex is best for complex reasoning tasks

When to Escalate

Use Codex for:

• Implementation requiring extended thinking
• Multi-file refactoring
• Complex code generation
• Architecture planning

Use specialized ras-commander agents for:

• HDF analysis -> hdf-analyst
• Geometry parsing -> geometry-parser
• USGS integration -> usgs-integrator

See Also:

• code-oracle-codex agent - Full orchestration capabilities
• .claude/rules/subagent-output-pattern.md - Output format standards