# Agent Codex

> Use when the user mentions Codex, wants to delegate any coding task, says "let Codex handle this", "codex solve", "ask Codex", or wants a second implementation pass, bug investigation, code review, architecture analysis, or independent coding subtask handed off to OpenAI Codex. Trigger even when the user doesn't say "Codex" explicitly — if the task is substantial, self-contained, and would benefit from a separate agent working independently, this skill applies.

- Skill: `ray0907/agent-codex` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add ray0907/agent-codex`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ray0907/agent-codex/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: ray0907 (https://skillmd.com/u/ray0907)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ray0907/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:

| Role | sandbox | approval-policy | When to use |
|------|---------|-----------------|-------------|
| **explorer** | `read-only` | `untrusted` | Analyze code, review architecture, explain flows, find bugs — no file changes |
| **worker** | `workspace-write` | `on-failure` | Implement features, fix bugs, refactor — the default for most tasks |
| **monitor** | `read-only` | `untrusted` | Poll CI status, watch build output, wait for deploy |

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

```bash
# 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:

```bash
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.