Codex Subagent

Hand off a task to Codex CLI for autonomous execution. Codex is a capable coding agent that can implement features, fix bugs, refactor code, investigate issues, and review changes.

Session Info

Session ID: ${CLAUDE_SESSION_ID} Output directory: ~/.claude/codex/${CLAUDE_SESSION_ID}/

Parse Arguments

Arguments: $ARGUMENTS

Parse the arguments:

Everything before flags is the task description
--model <model> or -m <model>: Override model (only if explicitly requested)
--sandbox <mode>: Override sandbox mode (only if explicitly requested)

Available models (only pass if user explicitly requests):

gpt-5.2-codex - Default for Codex CLI, optimized for agentic coding (user's current config)
gpt-5.2 - Flagship model, best for complex professional tasks
gpt-5-mini - Fast, cost-efficient (replaces o4-mini)
o3 - Deep reasoning model for complex multi-step problems

Sandbox modes (only pass if user explicitly requests):

read-only - No file modifications allowed
workspace-write - Can modify files in workspace
danger-full-access - Full system access (use with caution)

Default behavior: Omit --model and --sandbox flags to use the user's ~/.codex/config.toml preferences.

If no task description provided, ask the user what they want Codex to do.

Assess Task Complexity

Based on the task description, determine context depth:

Minimal context (single file fix, simple query):

Task mentions specific file or function
Clear, scoped objective
Example: "fix the type error in auth.ts", "add logging to handleRequest"

Medium context (feature work, multi-file change):

Task involves a feature or component
May touch multiple files
Example: "add input validation to the API", "refactor error handling"

Full context (architectural, investigation, unclear scope):

Task is exploratory or investigative
Scope unclear or potentially large
Example: "figure out why tests are flaky", "improve performance"

Gather Context

Git State (always include)

pwd
git rev-parse --show-toplevel 2>/dev/null || echo "Not a git repo"
git branch --show-current 2>/dev/null || echo "N/A"
git status --short 2>/dev/null | head -20

For Medium/Full Context

git diff --stat 2>/dev/null | tail -20
git log --oneline -5 --since="4 hours ago" 2>/dev/null || echo "No recent commits"

For Full Context Only

Summarize relevant session context:

What was being worked on
Key decisions or approaches discussed
Files that were read or modified
Any blockers or open questions

Generate Codex Prompt

Create a prompt using CTCO structure (Context → Task → Constraints → Output format) optimized for GPT-5.2.

Structure:

<context>
Working directory: {cwd}
Repository: {repo_name}
Branch: {branch}

{git_status if relevant}
{recent_changes if medium/full context}
{session_summary if full context}
</context>

<task>
{task description from arguments}
</task>

<constraints>
- Implement EXACTLY and ONLY what is requested
- No extra features, refactoring, or "improvements" beyond the task
- Read relevant files before making changes
- Run tests/linters if available to validate changes
- If task is ambiguous, state your interpretation before proceeding
</constraints>

<output>
After completing the task, provide a structured summary (≤5 bullets):
- **What changed**: Files modified and nature of changes
- **Where**: Specific locations (file:line when relevant)
- **Validation**: Tests run, linters passed, manual verification
- **Risks**: Any potential issues or edge cases to watch
- **Next steps**: Follow-up work if any (or "None")
</output>

Execute Codex

First, ensure output directory exists:

mkdir -p ~/.claude/codex/${CLAUDE_SESSION_ID}

Check if we're in a git repo:

git rev-parse --show-toplevel 2>/dev/null && echo "IN_GIT_REPO" || echo "NOT_GIT_REPO"

Build and run the command:

codex exec --json \
  -o ~/.claude/codex/${CLAUDE_SESSION_ID}/output-{timestamp}.txt \
  {required_flags} \
  {optional_flags} \
  - <<'CODEX_PROMPT'
{generated_prompt}
CODEX_PROMPT

Flag rules:

If NOT in a git repo: add --skip-git-repo-check (required)
Default: add --full-auto (enables workspace-write sandbox + auto-approval)
If user requests read-only: use --sandbox read-only instead of --full-auto
If user requests specific model: add -m <model>
If user requests danger-full-access: use --sandbox danger-full-access instead of --full-auto

Run via Bash tool. For long-running tasks, use run_in_background: true.

Monitoring Execution

The --json flag streams JSONL events. Key event types:

agent_message: Codex's responses
tool_call: Tools being executed
error: Errors encountered

If running in foreground, output streams naturally. If backgrounded, use tail -f on the output file or check TaskOutput.

Return Result

When Codex completes:

Read the output file from ~/.claude/codex/${CLAUDE_SESSION_ID}/
Parse Codex's structured summary
Report concisely to the user (3-6 sentences or ≤5 bullets)

Format:

## Codex Result

**Status:** {success/error/partial}

**What changed:**
- {file1}: {change summary}
- {file2}: {change summary}

**Validation:** {tests/linters run, results}

**Risks/Notes:** {if any, otherwise omit}

**Next steps:** {if any, otherwise "None"}

Keep the summary concise. If Codex produced verbose output, distill to essentials.

Examples

Simple fix

/codex fix the null pointer in utils/parser.ts line 42

Minimal context, quick execution.

Feature implementation

/codex add rate limiting to the /api/submit endpoint

Medium context, may take a few minutes.

Investigation

/codex investigate why the CI build fails on arm64

Full context, potentially long-running, consider backgrounding.

With model override (only when explicitly requested)

/codex --model o3 design a caching strategy for the database queries

Read-only mode (for review/analysis tasks)

/codex --sandbox read-only review the authentication implementation

Skips --full-auto, uses read-only sandbox for safe exploration.