Invoking Codex CLI

Delegate tasks to Codex CLI using markdown files for instruction input and deliverable output. Write instructions to TASK.md, invoke Codex, then read OUTPUT.md for results.

Pattern: Markdown File Handoff

code

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:

•Eliminates shell escaping issues (quotes, special characters, code blocks)
•Keeps context structured in reviewable files
•Enforces explicit deliverable format
•Supports session resume via thread ID

When to Use

Use this skill for:

•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 instead of switching to older models.

Invocation

Standard Pattern (Recommended)

bash

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

bash

# 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

bash

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)

markdown

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

Instruct Codex to produce:

markdown

# 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

markdown

# 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

bash

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 the results, verify changes, and continue the workflow.

Environment Variables

bash

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

Cross-References

Agents (delegate when needed):

•code-oracle-codex -- Delegate for deep code analysis with Codex

Skills (related workflows):

•dev_invoke_gemini-cli -- Alternative: Gemini CLI for large context analysis
•dev_invoke_kimi-cli -- Alternative: Kimi CLI for test generation
•qa_review_triple-model -- Uses this skill as one of three reviewers