codex-delegate
/codex-delegate
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.
- Author
- yongop ↗
- Repository
- codex-delegate ↗
- Licence
- MIT
- Last repository change
- 20.08.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 1
No signals detected. Repository changed on 20.08.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
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.
Triggers from the description
Original author 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.
How it works
- Workflow
- Prompting Codex (GPT-5.6) — distilled from OpenAI's official guide
- When to keep an edit yourself instead of delegating
- Setup (first use on a machine)
- Notes
SKILL.md preview
---
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.
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · yongop/codex-delegate | 90 | MIT |
| FrancoStino/opencode-skills-collection | 100 | MIT |
| kachofugetsu09/akashic-agent | 100 | MIT |
| wenyuchiou/codex-delegate | 100 | MIT |
| sickn33/agentic-awesome-skills | 100 | MIT |
| joezhuo2/delegate-skills | 100 | MIT |
| kcng0/cc-codex-run | 100 | MIT |
| amelnagdy/delegate-skills | 100 | MIT |
| smk-labs/claude-plugins | 100 | MIT |
Database snapshot: 13.11.2026 · package version 4df017ecb9ab (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 95dev_invoke_codex-cli
Delegate code tasks to OpenAI Codex CLI using markdown file handoff pattern. Write instructions to TASK.md, Codex reads and executes, outputs to OUTPUT.md. Use for implementation, refactoring, code generation requiring extended thinking. Triggers: codex, codex cli, delegate to… - 90model-cli-codex
Use when asked to use Codex, GPT, OpenAI, or the Codex CLI to delegate; write-enabled unless mode:plan. Not for messaging a Codex session. - 90codex
Use when asked to use Codex, GPT, OpenAI, or the Codex CLI to delegate; write-enabled unless mode:plan. Not for messaging a Codex session. - 100codex-rescue
Delegate an implementation task to Codex, then Claude reviews the result. Use when asked \"codex rescue\", \"delegate to codex\", \"have codex do it\", or wants Codex to implement or fix something. - 95gpt
Delegate a task to OpenAI Codex through the Quest CLI runner from Claude-led sessions. Use when the user invokes /gpt, asks to use codex, or wants a second opinion from a different model. - 100use-codex
Delegate independent codebase analysis, adversarial review, debugging, implementation, or patching to OpenAI Codex CLI as an external subagent. Use only when the user explicitly asks to use Codex, requests a Codex review or second opinion, or wants Codex to patch files. Route…