codex-delegate

---
name: codex-delegate
description: Delegates implementation-heavy or repetitive coding work (batch edits, boilerplate, multi-file refactors with clear patterns, test scaffolding) from Claude to OpenAI Codex CLI. Use when token cost outweighs judgment cost. Trigger phrases include "delegate to codex", "let codex do this", "batch refactor across files", "scaffold tests for". Avoid for architecture, security review, or root-cause debugging.
license: MIT
compatibility: Designed for Claude Code. Marketplace plugins use ${CLAUDE_PLUGIN_ROOT}/scripts/run_codex.sh; direct agentskills.io-compatible installations bundle scripts under <skill-root>/scripts/. Resolve paths for the installed host rather than assuming a user skills directory.
---

# Codex Delegate Skill

Claude is the supervisor. Codex CLI runs the mechanical work. Claude plans, constrains scope, reviews the diff, and verifies outcomes.

## Why use this instead of raw `codex exec`

Use this as a minimal adapter when the supervising workflow needs its legacy
sidecar/sentinel contract and on-disk brief convention. Native `codex exec
--json` already provides machine-readable events, and the official
[`openai/codex-plugin-cc`](https://github.com/openai/codex-plugin-cc) supplies
Claude Code delegation, job tracking, and resume. Prefer those facilities when
they satisfy the workflow; do not build another broker in this wrapper.

| What the wrapper handles | What raw `codex exec` costs you |
|---|---|
| **stdin closure** (`</dev/null`) | A direct caller must close stdin or use the CLI's intended prompt-input mode. A historical session hit a 25-minute zero-byte hang on 2026-05-14. This is not an exclusive wrapper capability. |
| **Legacy `.result.json` / sentinel contract** | A caller using native `--json` events must adapt them if a downstream consumer expects these sidecars. `risks` and `tests_run` remain empty placeholders until supervisor acceptance. |
| **Brief convention** (`references/task-template.md`) | Both direct Codex and the official plugin can receive the same scoped brief. The wrapper validates a brief path; it does not prevent drift or enforce allowed paths. Historical F11/F12 incidents motivate independent scope review. |

No matched live comparison has established superior coding quality or total
model-token savings for this wrapper versus the official plugin. The ratios
below compare delegation with an estimated Claude-inline control, not with
native Codex or the official plugin.

### Token-saving ratios (directional dogfood data — measured treatment, ESTIMATED control)

From a 6-round mixed-workload session (`awesome-agentic-ai-zh` 2026-05-14, see `agent-collab-skills/docs/measured-benefits.md`). Honest methodology note (per that doc's own words): the delegated arm was measured (bytes/3 proxy), the Claude-inline control arm was "estimated, not measured, because we didn't run the control condition" — treat every ratio below as directional, not a precise multiplier. The 17-22× row was additionally produced on the since-retired gemini lane (R4 of that session) and has not been re-measured on Codex.

| Workload | Saving vs Claude-inline | When it applies to you |
|---|---|---|
| **Mechanical sweep × 2 parallel** (e.g., term replacement, § strip, doc renumber) | **~7× token reduction** + caught 4 drift files | Repo with > 20 files needing the same edit |
| **Mirror sync** (zh-TW → zh-Hans + en, 8 files) | **17-22× token reduction** | Multi-locale docs / curricula |
| **Multi-file rename / typed-API migration** | ~3× (extrapolated from Phase D title-sweep) | > 10 files following one pattern |
| **Single-file < 50 line fix** | **~1× (don't bother)** | Use Claude direct Edit |
| **Architecture / debugging / security review** | **1× (skill cannot help)** | Claude direct |

The wrapper helps for **token-heavy mechanical work**. It does not help for judgment-heavy work — be honest about which one your task is.

### Anti-patterns this skill prevents

- **F11**: Codex over-applies a sweep rule to documentation describing that rule. Prevented by `agent-task-splitter` brief that explicitly lists in-scope files.
- **F14**: Operator (Claude) defaults to `Bash("codex exec ...")` despite the rule saying use `Skill("codex-delegate")`. Prevented by a `PreToolUse` hook on the operator side (template below).
- **Codex hang**: 25-minute zero-byte run on 2026-05-14 because raw `codex exec` was invoked without `</dev/null`. Prevented by wrapper's mandatory stdin closure.

### CLAUDE.md snippet to enforce routing

Drop this into your `~/.claude/CLAUDE.md` (or repo-level `CLAUDE.md`) to make the rule operational rather than aspirational:

```markdown
## Codex routing rule (enforced)

For any task that is mechanical, multi-file, has a clear pattern, or
batch-edits ≥ 3 files (canonical tripwire: fable-style-project-harness/docs/codex-delegation-policy.md — single source; older ≥5 statements are superseded): invoke `Skill("codex-delegate", args="brief=...")`.
Do NOT use `Bash("codex exec ...")` for shipping tasks — it loses stdin
closure (codex hangs), the `.result.json` contract (no structured status),
and the brief template (Codex drifts F11/F12).

Optional mechanical enforcement: a PreToolUse hook on Bash that nudges raw
`codex exec` toward `Skill("codex-delegate")`. Reference implementation:
https://github.com/WenyuChiou/dotfiles-claude/blob/main/hooks/check_codex_skill_routing.py
```

→ The hook is non-blocking (warns only) so you can still run `codex --version` /
`codex exec resume` / `codex exec review` without friction. Replace `return 0`
with `return 2` in the hook to make it block instead of warn.

## Hard rules

- Before invoking the wrapper, run `codex --version` via Bash. If it fails, stop and tell the user to `npm install -g @openai/codex`.
- When calling `codex exec` directly (not through the wrapper), close stdin explicitly (`</dev/null`); the wrapper handles this internally.
- Wrapper run leaves machine-readable status at `<log-file>.result.json`. Acceptance is Claude's job, not the wrapper's.
- Do not wrap the wrapper in `Start-Process`. Call it inline so file writes persist.

## Brief discipline

The wrapper now enforces on-disk brief traceability (added 2026-05-15 after the research-hub v0.89.1 post-release audit caught 2 orphan results from inline `--prompt` dispatches with no brief on disk).

- **Brief MUST be on disk before invoking the wrapper.** Filename pattern: `.ai/codex_task_<NN_chronological_or_version>_<short_slug>.md` (e.g., `.ai/codex_task_v090_paginated_hub.md`). The brief is the audit record — if it's not on disk, post-hoc reconstruction is guesswork.
- **Pass `--brief-file <path>` (preferred)** instead of an inline `--prompt`. The wrapper auto-derives the prompt as `Read <brief> and execute all instructions inside.` and places results next to the brief at `<brief_stem>.txt` and `<brief_stem>.txt.result.json` — no more stem drift where briefs live in `.ai/` flat and results land in `.ai/2026/05/13/`.
- **Guard fires on inline `--prompt` > 500 chars with no brief reference.** Wrapper exits 2 with a fix-it message. Short inline prompts (e.g., `--prompt 'Read .ai/codex_task_v090.md and execute'`) still work — the guard only refuses long inline prompts that ship instructions Codex cannot trace back to a file.
- **Escape hatch:** `CODEX_DELEGATE_ALLOW_INLINE=1` (env var) bypasses the guard. Use this for one-off shell debugging only, never for shipping tasks.

## When to delegate

Mechanical → `codex` · Reasoning / long-context synthesis → `claude` (chunked; Gemini lane DEPRECATED 2026-06-18).

Full routing table and good/bad examples: `references/delegation-targets.md`.

## Workflow

1. **Brief**: write `.ai/codex_task_<name>.md` with Context / Goal / Constraints / Acceptance. Template: `references/task-template.md`. For a judgment-sensitive task (debugging, write-capable change, review, research) — where an unsupported guess or a half-finished fix would hurt — also add the XML prompt blocks from `references/codex-prompt-blocks.md` to the Goal/Constraints. A pure mechanical sweep does not need them. If the brief was already written by `agent-task-splitter` at `.ai/codex_task_<NNN>_<slug>.md`, read `.coord/plan.yml` for round context first.

2. **Run**: from Claude Code Bash, invoke the wrapper from its install location:
   ```bash
   bash "${CLAUDE_PLUGIN_ROOT}/scripts/run_codex.sh" \
     --brief-file .ai/codex_task_<name>.md \
     --repo "$PWD"
   ```
   With `--brief-file` the wrapper auto-derives the prompt and places results next to the brief at `.ai/codex_task_<name>.txt` and `.ai/codex_task_<name>.txt.result.json` (canonical location — eliminates the stem-drift class where briefs and results live in different subdirs). Override with `--log-file` only when you have a reason to. `--repo` defaults to the caller's `$PWD`; pass it explicitly to be defensive about the working directory at invocation. For direct skills installations, substitute `<skill-root>/scripts/run_codex.sh`; the packaged mirrors are self-contained. `--brief-file` resolves the accepted path absolutely before Codex changes cwd, with caller-first lookup and repo-relative fallback preserved. PowerShell variant + env vars: `references/wrapper.md`.

3. **Read status**: `cat .ai/codex_task_<name>.txt.result.json`.
   - `success` → diff still needs review.
   - `fallback` → Codex quota hit; Claude must take over.
   - `error` → wrapper failed; check `<log>.error`.

4. **Accept**: read the diff, confirm scope, run the verification commands listed in the task file. Reject if Codex drifted. Extended checklist: `references/review-checklist.md`.

## Output contract

`.result.json` includes at minimum: `status` (success|fallback|error), `delegate` ("codex"), `model`, `reasoning_effort`, `service_tier`, `log_file`, `output_file`, `summary`, `risks`, `files_changed`, `tests_run`, `timestamp_utc`. Full schema and status semantics: `references/output-contract.md`.

## Compatibility

- Tested with `@openai/codex` 0.128.0–0.144.1 (May–July 2026). Should work with any version that accepts `codex exec --sandbox workspace-write`.
- Wrapper default model: none. Without `--model` / `-Model` the wrapper passes no `-m`, so Codex uses its own configured default (reported as `codex/default`); pass `--model` or `-Model` to pick one. Availability and pricing depend on the account and installed CLI. `references/model-selection.md` contains a historical A/B snapshot, not a current price guarantee. Use the interactive `/model` picker to inspect available models.
- Wrapper default reasoning effort: none. Without `--effort` / `-Effort` (or `CODEX_DELEGATE_EFFORT`) the wrapper passes no `-c model_reasoning_effort`, so the effort in `~/.codex/config.toml` applies (reported as `default`). Pass `--effort <level>` (for example `low`, `medium`, `high`, `xhigh`) per call, or set `CODEX_DELEGATE_EFFORT` so delegation defaults to a cheaper effort than interactive use; the flag wins over the env var. See `references/model-selection.md`.
- Wrapper default service tier: none. Without `--service-tier` / `-ServiceTier` (or `CODEX_DELEGATE_SERVICE_TIER`) the wrapper passes no `-c service_tier`, so the tier in `~/.codex/config.toml` applies (reported as `default`). Pass `--service-tier <value>` (for example `fast` or `flex`) per call, or set `CODEX_DELEGATE_SERVICE_TIER`; the flag wins over the env var, and `default` passes nothing. See `references/model-selection.md`.
- Wrapper calls `codex exec --sandbox workspace-write -C <repo> [-m <model>] [-c model_reasoning_effort=<effort>] [-c service_tier="<tier>"]`. In observed CLI `0.159.0-alpha.7`, `-C`/`--cd` selects a working-root directory, not a context file; `--full-auto` is absent. Check `codex exec --help` for your installed version. See `references/runtime-compatibility.md` for the primary-source checks and limits.
- `codex exec` is non-interactive. Sandbox selection is not blanket permission: the installed host's approval and policy settings still apply. The observed CLI has no exec-local `--ask-for-approval` option; do not infer bypassed approval or expand access from that absence.
- Direct `codex exec` calls must close stdin (`</dev/null`) to avoid the historical hang (issue #20919).
- PowerShell wrapper requires `$ErrorActionPreference` to NOT be `Stop` so stderr writes (warnings, banners) don't trip the catch block.

## Harness-aware delegation (target repo carries the fable-method-harness pointer)

If the target repo's `AGENTS.md` carries the conditional pointer generated by
the fable-method-harness (`python scripts/setup_harness.py --print-wiring`,
run in the harness repo),
do NOT re-teach harness discipline in the brief — the pointer's conditional
block decides activation per task (measured on Codex: 4/4 trigger recall,
0/2 routine over-trigger, 1/1 rollback; proof-of-instrument, not a
token-superiority A/B — see that harness's
`docs/runtime_activation_telemetry_2026_07_15.md`). A brief that restates
the discipline pays the context twice. For bidirectional multi-round work
(ai-review experiments, iterative implementation), use
`references/handoff-protocol.md` — files, not clipboard.

## See also

- `references/handoff-protocol.md` — bidirectional Fable↔Codex rounds via `.ai/handoff/` files (kills copy-paste); harness-aware brief rule; `codex exec --json` usage telemetry
- `references/delegation-targets.md` — when to use vs avoid
- `references/wrapper.md` — full wrapper invocation, env vars, Windows runner notes
- `references/task-template.md` — task brief template
- `references/codex-prompt-blocks.md` — XML prompt blocks + recipes + anti-patterns for judgment-sensitive briefs
- `references/output-contract.md` — full `.result.json` schema, status semantics, `.fallback_claude` quota sentinel
- `references/review-checklist.md` — extended acceptance gate
- `references/patterns.md` — five single-task delegation shapes (context file, parallel, resume, structured output, review mode)
- `references/multi-agent.md` — leaf role in router/leaves architecture; when to route through `research-hub-multi-ai` or `agent-task-splitter`
- `references/examples.md` — concrete invocation examples on `codex-cli` 0.128.0+ syntax
- `references/model-selection.md` — when to pass `--model` / `--effort` / `--service-tier`, plus a historical A/B snapshot of a cheaper vs a pricier model

• SKILL.md 14 KB
• references/codex-prompt-blocks.md 8 KB
• references/delegation-targets.md 2 KB
• references/examples.md 4 KB
• references/handoff-protocol.md 4 KB
• references/model-selection.md 8 KB
• references/multi-agent.md 3 KB
• references/output-contract.md 4 KB
• references/patterns.md 4 KB
• references/review-checklist.md 1 KB
• references/runtime-compatibility.md 4 KB
• references/task-template.md 2 KB
• references/wrapper.md 5 KB
• scripts/run_codex.ps1 17 KB
• scripts/run_codex.sh 14 KB