codex-delegate
/codex-delegate
Delegate a coding task to the OpenAI Codex CLI as a background implementer, then review its diff and land it yourself. Use this whenever the user wants to hand implementation work to Codex — phrasings like "have Codex do X", "delegate this to Codex", "run it through Codex", or "use Codex to implement/fix/refactor" — or to run a queue of coding tasks through Codex while staying the reviewer. Prefer it over a one-shot Codex forwarder (such as the codex-rescue agent) when the user will review the diff and commit it themselves. DO NOT USE for tasks small enough to do inline, or when the user wants
- Author
- amelnagdy ↗
- Repository
- delegate-skills ↗
- Licence
- MIT
- Last repository change
- 14.10.2026
Assessment and security
- Files in this package
- 6
- Scripts
- 1
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 14.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- 1 scripts in this package. Review them before installing, as Claude may execute them.
Scripts: scripts/relay.mjs
What it does and when to use it
Delegate a coding task to the OpenAI Codex CLI as a background implementer, then review its diff and land it yourself. Use this whenever the user wants to hand implementation work to Codex — phrasings like "have Codex do X", "delegate this to Codex", "run it through Codex", or "use Codex to implement/fix/refactor" — or to run a queue of coding tasks through Codex while staying the reviewer. Prefer it over a one-shot Codex forwarder (such as the codex-rescue agent) when the user will review the diff and commit it themselves. DO NOT USE for tasks small enough to do inline, or when the user wants
Triggers from the description
Original author description
Delegate a coding task to the OpenAI Codex CLI as a background implementer, then review its diff and land it yourself. Use this whenever the user wants to hand implementation work to Codex — phrasings like "have Codex do X", "delegate this to Codex", "run it through Codex", or "use Codex to implement/fix/refactor" — or to run a queue of coding tasks through Codex while staying the reviewer. Prefer it over a one-shot Codex forwarder (such as the codex-rescue agent) when the user will review the diff and commit it themselves. DO NOT USE for tasks small enough to do inline, or when the user wants
How it works
- When NOT to use this
- Prerequisites (check once)
- The loop
- Read-only second opinions
- Authorization model
- If you have the openai-codex plugin
- References
SKILL.md preview
---
name: codex-delegate
description: >-
Delegate a coding task to the OpenAI Codex CLI as a background implementer, then review its diff and
land it yourself. Use this whenever the user wants to hand implementation work to Codex — phrasings
like "have Codex do X", "delegate this to Codex", "run it through Codex", or "use Codex to
implement/fix/refactor" — or to run a queue of coding tasks through Codex while staying the reviewer.
Prefer it over a one-shot Codex forwarder (such as the codex-rescue agent) when the user will review
the diff and commit it themselves. DO NOT USE for tasks small enough to do inline, or when the user
wants the code written directly without delegating.
license: MIT
compatibility: Requires the `codex` CLI (OpenAI Codex) installed and authenticated, Node 18+, and git. The orchestrating agent must be able to run shell commands and read files. Shell examples assume bash/zsh (macOS/Linux, or Git Bash/WSL on Windows).
metadata:
version: 0.5.0
---
# 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](references/writing-the-brief.md).
This skill selects Codex as the **implementer**. Codex as the **orchestrator** is a separate role:
background waiting requires codex-background and its configured MCP server. Installing
codex-delegate does not automatically install or configure that support utility. See the
[codex-background setup guide](../codex-background/references/configuration.md).
### 2. Dispatch
For **Codex orchestration of background work**, install and configure the separate
**codex-background** support utility first. If its MCP tools or registry are missing, stop and
report the setup requirement; do not silently fall back to model-driven polling. Then invoke its
registered `delegate_run` MCP tool once in place of the shell example below.
Follow that skill for structured common arguments, unchanged provider flags and reattachment by
runId. Keep the request pending until completion, then continue this skill's review and landing
steps. Other orchestrators keep the shell workflow below.
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.)
```bash
node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --cd /path/to/repo
# read-only (review/diagnosis, no edits): add --read-only
# isolated review (skip ambient MCP/user config): add --ignore-user-config
# subagent defaults: add --subagent-model <name> --subagent-effort <level> (again on every resume)
# web search mode (disabled|cached|indexed|live): add --web-search live (again on every resume)
# network inside the sandbox (gh, curl, installs): add --network-access (on resume: --sandbox workspace-write --network-access)
# continue the exact Codex session: add --session <threadId> (from result.json; send only the delta brief)
# fallback when no thread id is available: add --resume-last
# hard time limit (watchdog): add --timeout 2h (default: off; implementation runs routinely need 1-2h)
# 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](references/dispatch-and-poll.md).
### 3. Wait for completion
Codex using codex-background keeps the original MCP request pending: no model-driven sleep,
status or log polling. Use `delegate_wait` only to reattach after an interrupted request.
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. The implementer's full report is
the `finalMessage` field in `result.json` (also printed in full on stdout between the report markers).
### 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](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 `--session <threadId>` from the prior `result.json`
(use `--resume-last` only when no thread id is available), and review again.
## Read-only second opinions
The relay doubles as a clean way to get an adversarial second opinion with no write risk: dispatch
`--read-only` with a brief that lists the agreed points, then each contested point with both
positions, and ask Codex to defend or concede each — deliverable in its final message, touching no
files. Any delegation skill whose implementer offers a read-only mode supports the same use, but
check how hard that mode's guarantee is first: Codex's sandbox enforces it, while Grok's is
best-effort and only flagged after the fact (`readOnlyViolation`) — for those implementers,
verify `touchedFiles` came back empty instead of assuming no edits.
## 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](references/review-and-land.md).
## If you have the openai-codex plugin
The official openai-codex Claude Code plugin is excellent and **complementary** — `codex-delegate`
builds on the same `codex` CLI, it doesn't replace the plugin. They point in different directions:
- The plugin's `codex:codex-rescue` agent is a **forwarder**: it hands one task to Codex and returns
the output. It deliberately does not poll, review, or commit.
- The plugin's review command and stop-review gate run the **inverse** direction: **Codex reviews your work**.
- `codex-delegate` is the **orchestration loop in the other direction**: *you* drive Codex to
implement across one task or a queue, and *you* review and land each result. That loop — brief →
dispatch → poll → review → commit, with the orchestrator owning the commit — is what the plugin
leaves to you, and what this skill encodes.
If you have the plugin installed, its companion CLI is an optional alternative dispatch backend; the
bundled `relay.mjs` is the default because it adds no install of its own beyond the `codex` binary
(Node and `git`, which the relay also needs, are prerequisites for every skill here).
## References
- [references/writing-the-brief.md](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](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](references/review-and-land.md) — the review checklist, the commit
boundary, and the exact-session rework cycle.
- [references/multi-task-queues.md](references/multi-task-queues.md) — running a sequential queue:
carrying constraints forward, progress tracking, and the end-of-run coherence check.
Files in this package (6)
- SKILL.md 11 KB
- references/dispatch-and-poll.md 18 KB
- references/multi-task-queues.md 4 KB
- references/review-and-land.md 8 KB
- references/writing-the-brief.md 6 KB
- scripts/relay.mjs 38 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · amelnagdy/delegate-skills | 100 | 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 |
| smk-labs/claude-plugins | 100 | MIT |
| Song-Sungyoub/claude-codex-delegate | 95 | MIT |
Identical content appears in 1 other GitHub folders. We show one copy with the highest score.
Database snapshot: 13.11.2026 · package version 8ffcd551a696 (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
- 100commandcode-delegate
Delegate a coding task to the Command Code CLI (`cmd`) as a background implementer, then review its diff and land it yourself. Use this whenever the user wants to hand implementation work to Command Code — phrasings like "have Command Code do X", "delegate this to commandcode",… - 100pi-delegate
Delegate a coding task to the Pi coding agent CLI (`pi`) as a background implementer, then review its diff and land it yourself. Use this whenever the user wants to delegate implementation work to Pi - phrasings like "have Pi implement X", "delegate this to pi", "run it through… - 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. - 100local-codex
Launches and manages the local OpenAI Codex CLI as a non-interactive coding sub-agent via ChatGPT OAuth, never API keys. Use to delegate coding tasks to Codex, run codex exec, generate or refactor code, or get a Codex code review; phrases like 'codex', 'run codex', 'codex exec', 'delegate to codex'. - 100delegate
Delegate a sub-task to OpenAI Codex CLI. Use when a task is better handled by Codex (e.g. complex file editing, multi-step coding tasks, automated code generation). - 100implement
Delegate a coding task to a Codex subagent (GPT 6.1 Sol by default) that writes files directly in the working directory. Use when the user wants Codex — or "GPT-5.5" — to build, implement, write, add, refactor, fix, or otherwise change code, whether they say "have Codex do X",…