codex-delegate

name

codex-delegate

description

Orchestrate an implementation task where Claude plans and coordinates while OpenAI Codex performs the actual code edits; plans are cross-reviewed with Codex at its highest reasoning effort before implementation. Use when the user asks to "use codex", "use gpt", "use gpt-5.5", "use gpt-5.6", delegate implementation to Codex, or wants Claude to plan/review while another model does the edits. Requires the `codex` CLI (installed) and the `codex-shell` subagent.

codex-delegate — plan with Claude, implement with Codex

Division of labor:

• You (Claude Code) own understanding, planning, orchestration, and verification.
• Codex, reached via the codex-shell subagent, performs the actual file edits under your precise instructions. (The exact Codex model and per-mode reasoning efforts are configured in that subagent's Config block — currently GPT-5.6-sol.)

The user drives this deliberately: Claude builds the plan and keeps the big picture; Codex is the hands that write the diff. Do not do the implementation edits yourself unless the user says so — hand them to Codex.

Workflow

1. Understand & plan. Explore the relevant code yourself (Read/Grep/Glob). Produce a concrete, ordered plan: which files change, what each change is, and how you'll verify it.

2. Cross-review the plan with Codex (plan-review mode). For any non-trivial task, before delegating implementation, spawn codex-shell in plan-review mode and have Codex critique your draft plan:

   • Write the plan you send in the shape GPT-5.6 expects an implementation plan to take (per the official guide): requirements, named files, state transitions or data flow, validation checks, failure behavior, security/privacy considerations if any, and open questions. Include key code excerpts it can't see otherwise.
   • Frame the request as review-only, and ask for a structured verdict: for each issue, what's wrong, why it matters, and the concrete fix — covering missed files/callers, ordering problems, risky assumptions, simpler alternatives, and gaps in the validation plan. Tell it to separate confirmed defects from speculation, and to say "no blocking issues" if that's the finding.
   • This run uses read-only sandbox at the subagent's plan-review reasoning effort (the subagent knows this mode — tell it "plan-review mode").
   • Incorporate the feedback yourself. You stay the plan owner: adopt points that survive your own scrutiny, reject the rest, and revise the plan.
   • Optional follow-up — at most 1 extra turn. If Codex's review raises something you can't settle from context, you may continue the same subagent via SendMessage exactly once: either ask a clarifying question or request a specific read-only investigation (e.g. "check whether X is also called from Y"). Fold the answer into the plan. Do not loop beyond this one follow-up turn — if disagreement remains, note both positions and decide yourself.
   • Skip this step only for trivial tasks (a change so small the plan is self-evident) or when the user explicitly says to skip plan review.
   • One plan-review per master plan. If the plan (or the design it derives from) already passed a plan-review, do not re-review per-phase breakdowns of it — self-verify those against the code and focus verification effort on the implementation results. If a breakdown introduces a genuinely new architectural decision, review just that part, narrowly scoped.
   • Large payloads (> ~10k-line diffs) exhaust high-effort runs. Codex at high reasoning effort can spend its whole turn investigating and end without emitting the report. Split large reviews into scoped passes (per subsystem or file cluster), or run one broad pass and re-run with its partial leads pre-seeded. Always instruct it to emit findings incrementally, not only at the end.

3. Confirm with the user. For non-trivial work, present the revised plan — including what Codex's review changed (or that you rejected its suggestions and why) — before delegating implementation.

4. Delegate implementation to Codex — one clear unit at a time. Spawn the codex-shell subagent (via the Agent tool, subagent_type: codex-shell). Write the task outcome-first (see "Prompting Codex" below): define the destination and the completion bar, name the files, and let Codex choose the path. Structure each delegation as:

   • Goal — the user-visible outcome of this unit, one or two sentences.
   • Success criteria — what must be true before it stops (behavior, interfaces or signatures to match, which validation must pass).
   • Files & constraints — the files/functions in scope, existing patterns to follow, don't-touch areas. State each constraint once.
   • Validation — the checks to run before finishing (targeted tests, type check, build for the affected package), and to report results.
   • Stop rules — when to stop and report back instead of improvising (e.g. required interface missing, change would expand scope, validation can't run). Codex runs in workspace-write and will edit files directly.

   Every delegation prompt must also carry these standing guards (each learned from a real incident):

   • Git guard — "do NOT git add/commit/push; leave changes in the working tree for review. Acceptance is verified via the unit's scoped diff, never global git-status cleanliness."
   • Parallel runs share one working tree (no worktree isolation). When units run concurrently, each prompt must additionally state: other agents are legitimately editing the same tree, so extra modified files in git status are EXPECTED; git checkout --/restore/stash/clean and deleting files outside the unit's scope are forbidden. Prefer file-disjoint scopes, or serialize the units.
   • Synchronous wait — "do not stop until the codex result is in hand; wait in the foreground until the codex process exits, then report its output." (The subagent has standing rules for this, but restate it — stalled background runs have been the most common delegation failure.)

   Prefer small, verifiable units over one giant delegation — it's easier to review and to localize failures.

5. Verify each unit yourself. After Codex returns, read the actual diff — scoped to the unit's files (git diff -- <its files>) — and run the project's checks (e.g. npx tsc, npx vitest, relevant tests). Do NOT trust Codex's self-report alone — confirm against the real tree. Also check git log (not just git status) to catch unrequested commits. After parallel units: re-check that earlier units' diffs still exist once later units finish, and before acting on any "scope violation" report from a unit, cross-check it against the sibling units' assigned scopes — units have misattributed each other's legitimate diffs as violations.

6. Iterate. If verification fails or the change is off, send a corrected, more specific instruction back to the same Codex run (continue the subagent via SendMessage) or spawn a fresh delegation. Keep the loop tight.

   • Stall recovery: if the subagent goes quiet with codex still running in the background, do not relaunch — the codex process usually survives. Nudge the same subagent via SendMessage ("process X is still running — poll until exit, then report") to collect the finished result.
   • Completion check: a codex session can end mid-task with no closing message. Have the subagent (or verify yourself) check deliverables against the task list, not just the final message; a follow-up "finish the remaining deliverables" run completes it cleanly.

7. Report. Summarize what changed, what you verified, and anything still open.

Prompting Codex (GPT-5.6) — distilled from OpenAI's official guide

Source: https://developers.openai.com/api/docs/guides/prompt-guidance-gpt-5p6

• Outcome-first, not step-by-step. Define the outcome, the constraints, the evidence available, and the completion bar — then leave room for the model to choose an efficient path. Don't prescribe every intermediate step.
• Keep prompts lean. State each rule exactly once. Drop repeated instructions, boilerplate style rules, and context that doesn't change behavior — OpenAI measured leaner prompts improving coding-agent scores by ~10–15% while cutting tokens 41–66%. Include only the code excerpts the task actually needs.
• Reserve ALWAYS/NEVER for true invariants (safety, required interfaces, don't-touch areas), not judgment calls. Absolute language on judgment calls degrades its decisions.
• Set autonomy boundaries explicitly. For review/plan/diagnose requests, say "inspect and report — do not implement changes." For implementation requests, authorize in-scope edits and non-destructive validation without asking, and require it to stop before anything destructive or scope-expanding.
• Demand validation before finishing. Tell it to run the most relevant checks (targeted tests, type check, build) after changing code, and if a check can't run, to say why and name the next-best check.
• Give stop rules, not just goals. Say when to stop, ask, or report a blocker instead of improvising past missing evidence.
• Expect conciseness. GPT-5.6 is more concise by default than earlier models — don't add "be brief" boilerplate; instead specify what the answer must contain (e.g. the structured verdict format in plan-review mode).

When to keep an edit yourself instead of delegating

• Trivial one-liners where a round-trip to Codex costs more than it saves.
• Orchestration glue, plan files, or notes — not the substantive implementation. Everything substantive that the user wants Codex to own, delegate.

Setup (first use on a machine)

This plugin installs two pieces that only work together:

• this skill (the orchestration playbook)
• the codex-shell subagent (the delegation shell; the Codex model and per-mode reasoning efforts are configured there, in its Config block)

Prerequisites:

1. Install the codex CLI: npm install -g @openai/codex (this skill was verified with codex-cli 0.144.1).
2. Authenticate: run codex login in a terminal (needs an OpenAI account with access to the model named in the subagent's Config).
3. Smoke test — this should print a short reply, not an auth or model error: codex -a never exec -m gpt-5.6-sol -s read-only --ephemeral - <<< "reply with ok" (substitute the model from the subagent's Config if it differs).
4. To avoid a permission prompt on every delegation, allow the codex commands in the project's shared .claude/settings.json: "Bash(codex --version)", "Bash(codex exec --help)", "Bash(codex -a never exec:*)".

Notes

• The Codex model and per-mode reasoning efforts are defined once, in the codex-shell subagent's Config block — change them there, not here. Details of the exact CLI invocation also live in that subagent — you don't construct the codex command yourself; the subagent does.
• If the codex CLI is missing or auth fails, the subagent reports the raw error — surface it to the user rather than silently falling back to editing yourself.