Agent Codex

Agent Codex

Delegate a coding task to OpenAI Codex in the current working directory.

1. Choose a Role

Select the role that best fits the task:

Default to worker when unclear.

2. Decompose the Task

Before calling Codex, analyze the task and decide how to split it. This decision belongs here — the caller doesn't need to pre-decompose.

Analysis steps:

1. Identify distinct subtasks in the request
2. For each pair, check: does subtask B need subtask A's output before it can start?
3. Check: do any two subtasks write the same files?

Decision rules:

• If subtasks are independent (no output dependency, no overlapping files) → run in parallel
• If subtasks depend on each other's output → run sequentially, each as its own Codex call
• If it's a single coherent task → single Codex call

Cap at 2–4 subtasks. More than 4 rarely helps and creates merge risk.

Show the decomposition plan before calling Codex. One line per subtask: name, role, why independent or sequential. This lets the caller catch misunderstandings before work starts.

Example output:

Decomposition plan:
1. Review auth architecture [explorer] — read-only, no dependency
2. Fix login bug [worker] — independent files (auth/login.ts)
→ Running in parallel

If the task is clearly single and simple, skip the plan and proceed directly.

3. Gather Project Context

bash <skill-dir>/scripts/prepare-context.sh

Include the output in the Codex prompt. Codex has no shared context — the prompt must stand on its own.

4. Prepare the Prompt

Use XML block structure so Codex can parse intent reliably:

<task>
  What needs to be done (the user's request, rewritten clearly).
  Include relevant file paths.
</task>

<project_context>
  Output from prepare-context.sh (stack, conventions, git status).
</project_context>

<constraints>
  Any rules beyond the project conventions (scope limits, files to avoid, etc.)
</constraints>

<verification_loop>
  After implementing, verify: run tests, check for errors, confirm each AC is met.
  If something fails, fix it before finishing.
</verification_loop>

For review tasks, replace <verification_loop> with <grounding_rules>: every finding must cite a specific file and line, no invented issues.

See references/codex-cli.md for CLI reference.

5. Call Codex

If MCP tool mcp__codex__codex is available:

mcp__codex__codex(
  prompt: <prepared prompt>,
  cwd: <working directory>,
  approval-policy: <from role>,
  sandbox: <from role>,
  developer-instructions: <project conventions>  // optional
)

Save the returned threadId for follow-up.

Otherwise (CLI):

# worker
codex exec -s workspace-write -a on-failure "<prompt>"

# explorer / monitor
codex exec -s read-only -a untrusted "<prompt>"

For multi-agent tasks: call in parallel, one per subtask, each gets its own role and prompt.

6. Follow-up

If MCP available:

mcp__codex__codex-reply(threadId: <id>, prompt: "<follow-up>")

Otherwise:

codex resume <session-id> "<follow-up>"
# or, for most recent session:
codex resume --last "<follow-up>"

7. Present Results

After Codex completes:

• List files changed and what was fixed or implemented
• Preserve Codex's findings verbatim — do not paraphrase or silently correct
• For review output: present findings first, ordered by severity. Then stop. Do not apply any fixes. Do not suggest you are about to make changes. Ask the user explicitly which issues, if any, they want addressed before touching a single file
• For failed or incomplete runs: report the failure and ask whether to retry with a refined prompt or send a follow-up

For multi-agent tasks: merge results from all subtasks, flag any file conflicts, resolve before reporting.

8. Rescue via Subagent

When Claude is stuck, needs a deeper diagnosis pass, or wants to hand a substantial task to Codex without orchestrating it manually — use the codex-rescue subagent directly:

Agent(subagent_type: "codex:codex-rescue", prompt: "<task description>")

The subagent is a thin forwarder: one Codex call, output returned verbatim. It uses the gpt-5-4-prompting skill internally to tighten the prompt before calling Codex.

For resume behavior: include --resume in the prompt to continue the latest Codex thread, --fresh to force a new session.