Codex Delegate

Codex Delegate

You are the orchestrator. This skill lets you hand a bounded coding task to a separate implementer — the OpenAI Codex CLI — then review what it produced and land it yourself. You write the brief and own the judgment; Codex does the typing in its own sandbox; you verify and commit.

Nothing here is specific to one orchestrating agent. The loop needs only the ability to run a shell command and read a file, so it works the same whether you are Claude Code, OpenCode with a selected model, or any comparable agent. (It is designed for and run on Claude Code; treat other orchestrators as designed-for, not yet proven.)

When NOT to use this

• The task is small enough to just do inline — delegation overhead is not worth it.
• The codex CLI is not installed or not authenticated (run codex login).
• You want to write the code yourself, or you only need a review (use Codex's own review command).

Prerequisites (check once)

1. codex --version succeeds. If not, install (npm i -g @openai/codex) and codex login. 2. Confirm which `codex` is on PATH. Multiple installs are common (e.g. a current npm/nvm copy and a stale Homebrew one). command -v codex shows the active one and codex --version its version — an old binary predates flags this skill relies on (codex exec --json, -o, exec resume). The relay also records the version it ran into result.json, so a stale binary is visible after the fact. 3. You are in (or will point --cd at) the target git repository.

The loop

Run these five steps per task. Steps 1, 4, and 5 are your judgment; 2 and 3 are mechanical.

1. Write the brief

Codex sees only the text you send — no repo memory, no chat history, no shared context. Everything the task needs goes in the brief: the goal, the current state, what to change, what to leave untouched, the project's actual gate commands (discover them from the repo's CLAUDE.md/AGENTS.md/Makefile — do not assume), and a report contract. Tell Codex it will not commit (you will). Keep one task per brief. Full guidance and a template: references/writing-the-brief.md.

2. Dispatch

Send the brief to Codex with the bundled helper. It wraps codex exec, captures the run, and writes a structured result.json — so your only job is "run a command, read a file." (<skill-dir> below is this skill's installed directory — the folder containing this SKILL.md, i.e. the directory you loaded the skill from. Claude Code prints it as "Base directory for this skill" when the skill loads; on other orchestrators use that same directory — if unsure where it landed, run find ~ -name relay.mjs -path '*codex-delegate*' and substitute the directory above it.)

node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --cd /path/to/repo
# read-only (review/diagnosis, no edits):   add --read-only
# continue the previous Codex session:      add --resume-last  (send only the delta brief)
# see all options:                          node .../relay.mjs --help

The helper defaults to a write-capable (workspace-write) sandbox and writes its artifacts to a temp dir, so the repo under review stays clean. It never commits — see step 5. Mechanics, flags, and the result.json shape: references/dispatch-and-poll.md.

3. Wait for completion

The helper blocks until Codex finishes, so back it with whatever your orchestrator offers and resume when it returns:

• Claude Code: run the Bash call with run_in_background: true; you are notified on completion.
• Plain shell / other agents: run it in the foreground for short tasks, or background it and poll

the result file — … & in bash/zsh (including Git Bash/WSL), or your shell's equivalent (Start-Job in PowerShell, start /b in cmd). The run is done when result.json exists with a status. (A pre-run usage error — bad args or an empty brief — instead exits with code 2 and a stderr message and writes no result file, so check the exit code too. A missing codex binary exits 127 but does write a result.json with status codex_unavailable.)

Do not trust progress trackers over reality: a run is finished when result.json is written and the process has exited. Read the working tree, not a status line.

4. Review — do not trust the self-report

Codex's result.json includes its own summary and gate claims. Re-verify, don't accept:

• Re-run the project's gates yourself (the test/lint/build commands from step 1). Never take

"gates passed" on faith.

• Read the diff against the brief: did Codex do what was asked, nothing more (scope creep) and

nothing less? touchedFiles in the result is your starting point.

• Run the relevant guard skills on the diff if you have them installed (clean-code-guard,

test-guard, etc. from guard-skills) — this skill produces the work; those skills judge it.

• For schema/migration changes, round-trip them; for removals, grep for dangling references.

Full checklist: references/review-and-land.md.

5. Land it

Because Codex's sandbox cannot reliably write .git (it varies by version, OS, and path), the orchestrator commits. Only after the gates pass and the diff holds:

• Commit the verified work yourself, with a clear message.
• If it needs changes, send a delta brief with --resume-last (don't restate the whole task) and

review again.

Non-negotiables

• Re-run the gates yourself. The self-report is a claim, not evidence.
• The orchestrator commits, never Codex. Don't assume Codex committed; it didn't.
• One task = one brief = one commit. Split unrelated work into separate runs.
• Trust the working tree and process state over any progress tracker.

Authorization model

Delegation is something the human opts into. Once they have ("run this queue", "proceed"), committing verified, gate-passing work is the agreed contract — that is the whole point. Two limits on that mandate: surface, don't absorb (report Codex's design decisions, defensible-but-unasked turns, and non-blocking nitpicks rather than silently keeping them) and stop for scope changes (if correct completion needs going beyond the brief, ask — don't expand the mandate yourself). The full treatment is in references/review-and-land.md.

Trust and safety

scripts/relay.mjs itself makes no network calls, reads or writes no credentials, and sends no telemetry; it has no dependencies (Node built-ins only) and shells out only to codex and git. The codex process it launches does authenticate — exactly as you do at the terminal. Read the script before you run it. It is the one executable in this package; everything else is Markdown.

References

• references/writing-the-brief.md — how to write a brief Codex can

execute blind: structure, XML blocks, the report contract, embedding the real gate commands.

• references/dispatch-and-poll.md — relay.mjs flags, the

result.json contract, backgrounding per orchestrator, and recovery when a run misbehaves.

• references/review-and-land.md — the review checklist, the commit

boundary, and the rework cycle via --resume-last.

• references/multi-task-queues.md — running a sequential queue:

carrying constraints forward, progress tracking, and the end-of-run coherence check.

What this skill does NOT do

• It does not commit for you — that is deliberate (step 5).
• It does not review the code's quality itself — pair it with guard skills.
• It does not run your tests — you re-run the project's own gates in step 4.
• It is not the inverse direction (Codex reviewing your work). For that, use the openai-codex plugin's

review command or stop-review gate.

Dispatch and poll

scripts/relay.mjs is the dispatch layer. It wraps codex exec, runs the brief in a sandbox, captures everything, and writes a structured result.json. Your job collapses to: run one command, then read one file. Everything Codex-specific lives in the helper, which is what keeps the loop portable across orchestrators.

Before the first run: check the binary

Two gotchas, both worth 30 seconds:

command -v codex      # the active binary; a stale install (e.g. Homebrew) can shadow a current one
codex --version       # an old binary predates `exec --json`, `-o`, and `exec resume`
codex login status    # must be authenticated

The Codex CLI moves fast and behavior shifts between versions, so the helper records the version it actually ran into result.json — if something behaves oddly, check which binary answered.

Dispatching

node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --cd /path/to/repo

(<skill-dir> is wherever this skill is installed — the folder containing its SKILL.md. On Claude Code it's the printed "Base directory for this skill"; on other orchestrators substitute that install path. See `SKILL.md` if you need to locate it.)

Options:

Artifacts default to the system temp dir on purpose: the repo under review stays clean, so the touched-files report shows only Codex's edits and nothing of the helper's own.

The result

<out-dir>/result.json is the contract. Fields:

• schema — the result-format version (currently delegate-relay.result.v1)
• status — completed | failed | codex_unavailable
• exitCode — mirrors Codex's exit code; 127 if codex isn't on PATH
• codexVersion — the binary that actually ran
• threadId — feed this to a later codex exec resume <id> (or use --resume-last)
• finalMessage — Codex's own final report (the <structured_output_contract> you asked for)
• touchedFiles — git status --porcelain lines in the working root: your review starting point. null (not []) when git can't report — git missing, or a non-repo run under --skip-git-repo-check; [] means git ran and the tree is clean
• briefPath / eventsPath / finalPath — the exact brief relay sent, the raw JSONL event stream, and the final-message file
• workdir, sandbox, model, resumeLast, startedAt, finishedAt
• stderrTail — last ~20 stderr lines; present only on a failed run (a non-zero Codex exit), absent on completed, codex_unavailable, and launch failures
• error — present only if Codex failed to launch

The helper also prints a summary to stdout and exits with Codex's exit code, so a wrapping script can branch on success/failure directly.

Waiting for completion

The helper blocks until Codex finishes. Back it with whatever your orchestrator offers:

• Claude Code: run the Bash call with run_in_background: true; you're notified on completion,

then read result.json.

• Plain shell / other agents: foreground for short tasks, or background and poll — `node relay.mjs

… & in bash/zsh (including Git Bash/WSL), or your shell's equivalent (Start-Job in PowerShell, start /b in cmd). A run is done when result.json exists with a status. **But** a pre-run usage error (bad args, empty brief) exits with code 2 *before* writing any file — so check the exit code too, don't only watch for the file. (A missing codex binary exits 127 but *does* write a result.json with status codex_unavailable`.)

Trust the working tree and the process state over any progress display. A run is finished when the process has exited and result.json is written — not when a status line says so.

When a run misbehaves

• `status: codex_unavailable` (exit 127): codex isn't on PATH or isn't found. Install

(npm i -g @openai/codex) and codex login, then re-dispatch.

• `status: failed`: read result.json's stderrTail and the tail of eventsPath for the cause.

Common causes: an auth lapse, an invalid --model, or a sandbox that blocked something the task needed. Fix the cause and re-dispatch; don't paper over it by doing the work yourself unless that's what the user wants.

• Empty `finalMessage`: Codex exited before producing a final message. Treat as a failed run;

the events log usually shows where it stopped.

What the helper is doing (and the alternatives)

Under the hood the helper runs roughly:

codex exec --json -o <final.txt> -s workspace-write [-m model] - < brief.txt   # fresh run
codex exec resume --last --json -o <final.txt> - < delta-brief.txt            # resume (no -s/-C)

resume deliberately gets no -s/-C — it inherits the original session's sandbox and working root — which is why the helper sets the child process's working directory instead.

Two alternatives exist if you ever want them, but the helper is the recommended path:

• Raw `codex exec` — fine for one-offs; you give up the captured result.json, touched-files

summary, and thread-id extraction the helper does for you.

• The openai-codex Claude Code plugin's companion CLI (task/status/result) — richer job

tracking if you have that plugin installed. It runs Codex as a background job behind a broker process, so you track jobs through queued/running states; the bundled helper instead spawns codex in-process and blocks until completion, so the only state to track is whether result.json exists — which is why it's the default here.

The commit boundary

The helper never commits — by design, not omission. Whether Codex's sandbox can write .git varies by version, OS, and execution path, so relying on it is a coin flip. The robust contract is: Codex edits the working tree, the orchestrator reviews and commits. See review-and-land.md.

Multi-task queues

The single-task loop scales to a queue, and that's where delegation pays off most — a removal split across layers, a migration touching many files, a refactor sweep. The discipline that makes a queue trustworthy is sequencing and bookkeeping, not parallelism.

Run sequentially, one commit per task

Resist the urge to fan out the whole queue at once. Run tasks one at a time, in dependency order, landing each (review + gates + commit) before dispatching the next. Three reasons:

• Later tasks assume earlier ones landed. Task 3's brief can say "the X added in the previous step

exists" only if the previous step actually committed.

• One commit per task keeps the history reviewable and any single step revertible.
• Each review is honest. A clean working tree before each dispatch means the next task's

touchedFiles shows only its changes, not a pile-up from earlier tasks.

Parallelism is occasionally worth it for genuinely independent tasks on separate files, but it sacrifices the clean-tree-per-task property and makes review harder. Default to sequential.

Carry decided constraints forward

Implementation surfaces facts the original plan didn't have: a helper got named, a fixture lives in a specific place, an interface was chosen. When a later task depends on one of those, fold it into that task's brief as an explicit line. Codex has no memory of the earlier run, so a constraint that emerged in task 2 must be restated in task 5's brief or it won't hold. This is the queue equivalent of keeping briefs self-contained.

Keep a progress file

For anything longer than two or three tasks — especially a run the human steps away from — maintain a single progress file alongside the work. It's the durable record that survives your own context limits and lets the human catch up at a glance. A shape that works:

• Status table — each task: queued / at-implementer / reviewed+committed (with the commit hash).
• Per-task review notes — what landed, what you verified, the gate outcome. One short paragraph.
• "Needs your eyes" — design decisions Codex made, non-blocking nitpicks, anything you want the

human to overrule or confirm. This is the section they read first.

• End-of-run checklist — what happens after the last task (push, open/update the PR, manual checks

the human should do).

Update it as each task lands, not in a batch at the end — if the run is interrupted, the file is still accurate.

Close with a coherence check

Per-task review proves each step in isolation; it doesn't prove the steps cohere. After the last task, verify the whole:

• Run the full test/build once more on the final tree — not just the last task's slice.
• Do a repo-wide check for the thing the queue was about (e.g. after a removal, grep the entire tree

for any surviving reference; after a rename, confirm no stragglers).

• For schema work, replay all the new migrations from a clean state and check for drift.
• Then push and open or update the PR, with a description that reflects what actually shipped.

When to stop and ask

Proceed without asking on anything that follows from the agreed plan — that's the point of the human opting into the queue. Stop and surface when:

• A task can't be completed correctly within its brief's scope (a scope change is the human's call).
• A review finds something that calls the plan into question, not just the implementation.
• The gates reveal a problem that affects tasks already "done."

Then report where you are, what's committed, and what the open question is — and wait. A queue that quietly works around a broken assumption produces a lot of commits in the wrong direction.

Review and land

Codex did the typing; you own the judgment. This is where delegation earns its keep or quietly ships a mistake. The discipline is simple to state and easy to skip under time pressure: verify against reality, never against the self-report, then commit it yourself.

Re-run the gates yourself

result.json carries Codex's own claim that the gates passed. Treat that as a claim, not evidence — re-run the project's actual test/lint/build commands in the working tree and read the output. A run that "passed" in Codex's report but fails when you run it is exactly the failure this step exists to catch, and it happens often enough to be worth the minute every time.

For changes with their own verification shape, go further:

• Migrations / schema: round-trip them (apply, reverse, re-apply on a scratch target) and check for

drift, rather than trusting that "the migration is reversible."

• Removals / renames: grep the codebase for dangling references to whatever was removed.
• Anything stateful: exercise the actual behavior, don't just confirm it compiles.

Read the diff against the brief

Open the diff (touchedFiles in the result is your starting list) and hold it against what you asked for:

• Scope creep — did Codex change things the brief said to leave untouched? Unasked refactors,

renames, "while I was here" edits. These are the most common quality problem in delegated work.

• Scope shortfall — did it do the whole task, including the edge cases and cleanup, or stop at the

first plausible version?

• Quiet judgment calls — sometimes Codex makes a defensible decision the brief didn't anticipate.

Don't just accept it because it looks reasonable; understand it and decide.

Compose with guard skills

This skill produces the work; it doesn't judge code quality. If you have the guard-skills package installed, run the relevant guard on Codex's diff before you commit — clean-code-guard on production code, test-guard on any tests it wrote, docs-guard on documentation. They catch the systematic failure modes of generated code that a quick read misses. The two packages are designed to pair: delegate-skills delegates and lands; guard-skills reviews.

The commit boundary

When the gates pass and the diff holds, you commit — the orchestrator, never Codex. This isn't a workaround for a missing feature; it's the deliberate boundary. Codex's sandbox can't reliably write .git, and more importantly, committing should be the act of the party that verified the work. Write a clear message describing what landed. If your project attributes co-authorship, that's the place for it.

Reworking: send the delta, not the whole task

If the review turns up problems, don't restate the entire brief. Continue the same Codex session with just the correction:

echo "The fix is right, but the test mocks the DB session - use the real migrated fixture instead, and
drop the now-unused import." | node "<skill-dir>/scripts/relay.mjs" --resume-last --cd /path/to/repo

(<skill-dir> is this skill's install directory — see dispatch-and-poll.md.)

--resume-last keeps Codex's context from the first run, so a short delta is enough. Then review again — rework gets the same gate-rerun and diff-read as the original, no shortcuts. Repeat until it's right, then commit.

Surface, don't absorb

The human opted into delegation, so committing verified, gate-passing work is the agreed contract. But keep them in the loop on anything that changes the shape of the work:

• Report design decisions Codex made, and any defensible-but-unrequested turns it took.
• Note non-blocking nitpicks you chose not to block on, so the human can overrule you.
• Stop and ask if correct completion requires going beyond the brief — don't expand the mandate on

your own. A scope change is the human's call, not yours or Codex's.

For a multi-task run, capture these in the progress file rather than letting them scroll past — see multi-task-queues.md.

Writing the brief

A brief is the entire task as Codex will see it. Codex runs in a fresh process with no memory of your conversation, no access to your prior notes, and no shared context — only the text you send and whatever it can read from the working tree (including the repo's own AGENTS.md, which it picks up automatically). If a constraint isn't in the brief or discoverable in the repo, it doesn't exist for Codex. The single most common failure is a brief that assumes context Codex doesn't have.

The shape that works

Codex responds best to compact, block-structured prompts with XML tags rather than long prose. State the task, what "done" looks like, how to behave by default, and the few constraints that actually matter. Add a block only when the task needs it — don't ship empty ceremony.

<task>
One or two sentences: the concrete job and where it lives. Then the specifics — current state, what to
change, and explicitly what to leave untouched. The "leave untouched" list is what keeps Codex from
wandering into unrelated refactors.
</task>

<verification_loop>
Run these before finishing and fix anything they surface, don't just report it:
  <the project's real test command>
  <the project's real lint/format command>
  <the project's real build/typecheck command>
Confirm the working tree shows only the intended changes afterward.
</verification_loop>

<action_safety>
Keep changes scoped to the task. No unrelated refactors, renames, or cleanup unless required for
correctness. Do NOT run git add or git commit — you cannot reliably write .git, and the orchestrator
commits after reviewing. Leave the work uncommitted in the working tree.
</action_safety>

<structured_output_contract>
End with a report in this exact shape:
  1. What changed and why
  2. Files touched
  3. Gate outcomes (paste the test/lint counts)
  4. Anything you deviated on, left open, or want a decision on
</structured_output_contract>

That four-block skeleton covers most implementation tasks. Reach for the extra blocks when the task profile calls for them:

• Debugging / open-ended fixes — add <completeness_contract> (resolve fully, don't stop at the

first plausible fix) and <missing_context_gating> (don't guess missing repo facts; find them or state what's unknown).

• Review / diagnosis (read-only) — add <grounding_rules> (ground every claim in evidence; label

inferences) and run with --read-only so Codex can't edit.

• Research / recommendations — add <research_mode> (separate observed facts, inferences, open

questions).

Discover the real gates — don't hardcode

<verification_loop> is only useful if it names the project's actual commands. Read the repo's CLAUDE.md / AGENTS.md / Makefile / package.json first and copy the real ones in (make test, npm run lint, cargo test, pytest -q, whatever it is). A brief that says "run the tests" without naming them gets you a Codex that guesses — or skips.

Honor the repo's conventions

Codex reads the repo's AGENTS.md automatically, so house rules there (style, forbidden patterns, commit conventions) already apply. If the project forbids certain things in code — say, spec/ticket IDs in comments, process language like "MVP"/"for now"/"phase N", or specific test conventions, whatever the repo's own conventions ban — restate the load-bearing ones in the brief too, because Codex's compliance is only as reliable as what's in front of it.

One task per brief

Keep each brief to a single, bounded job. "Review this, fix what you find, update the docs, and suggest a roadmap" produces a muddled run; split it into separate dispatches. One brief → one Codex run → one commit keeps review and rollback clean, and lets a later task assume the earlier one landed.

Expect environment preamble in the reply

Codex's final message may carry environment noise on top of your requested report — a banner injected by the repo's AGENTS.md, extra text from an MCP tool or extension you've configured, and similar local additions. That comes from your own Codex setup, not a relay defect. The <structured_output_contract> is your defense: ask for a clearly delimited report section so you can find the real output regardless of what wraps it.

A worked example

<task>
In the payments service at services/billing/, the refund path double-charges when a refund is retried
after a network timeout (the idempotency key isn't checked before re-submitting). Make the refund
submission idempotent: check for an existing refund by idempotency key before creating a new one.
Touch only services/billing/refund.py and its tests. Leave the charge path, the API routes, and the
data models untouched.
</task>

<verification_loop>
Run and make green before finishing:
  pytest tests/billing/ -q
  ruff check services/billing/
Confirm git status shows only refund.py and its test file changed.
</verification_loop>

<action_safety>
Scope strictly to the refund idempotency fix. No unrelated refactors. Do NOT git add or commit; leave
changes in the working tree for review.
</action_safety>

<structured_output_contract>
Report: (1) the root cause and your fix, (2) files touched, (3) pytest + ruff outcomes with counts,
(4) anything you left open or want decided.
</structured_output_contract>

Send this with relay.mjs (see dispatch-and-poll.md); review the result and commit it yourself (see review-and-land.md).