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

| Reasoning Effort | Use Case | Speed | |------------------|----------|-------| | xhigh | Default. Complex tasks, deep analysis | Slowest, best quality | | high | Medium complexity, good reasoning | Balanced | | medium | Lighter tasks, adequate reasoning | Faster | | low | Simple tasks, quick response | Fastest |

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

| Flag | Purpose | |------|---------| | -C /path | Working directory (where TASK.md lives) | | --full-auto | Sandboxed auto-execution (workspace-write + no approvals) | | --skip-git-repo-check | Work in any directory | | -c model_reasoning_effort=<level> | Reasoning: xhigh (default), high, medium, low |

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

Be explicit in TASK.md - Include all context, don't assume
Specify output structure - Tell Codex exactly what OUTPUT.md should contain
List input files - Explicitly name files Codex should read
Define constraints - Prevent unwanted modifications
Request thread ID - Include in deliverables for session resume
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