Skill: codex-exec
Purpose
Dispatch work to Codex through codex exec with correct flags, model, and output
bounding every time. Replaces the MCP-era codex-dispatch plugin skill, which is dead
since codex mcp-server was removed in codex-cli 0.156.1.
Gate (all three, every call)
- Target project CLAUDE.md contains a literal
codex=true line. Otherwise never call
codex.
OPENAI_API_KEY unset (subscription billing; set = silent API billing).
- codex-cli 0.156+ (
codex --version); gpt-6-* slugs 400 on older builds.
Inputs
- Task description or diff focus, plus the absolute path of the target repo.
Outputs
- Codex final message in the
-o <file> file. Exit code 0 = the session ran to
completion; still read the file to see whether Codex finished the task or stalled.
Call shape
codex exec -m gpt-6-luna -c model_reasoning_effort="max" \
--sandbox read-only -C /abs/target/repo -o /tmp/codex-answer.md "<prompt>"
| Flag |
Rule |
-C |
Absolute path of the TARGET repo, never the plan or workspace location |
--sandbox |
read-only for review and research, workspace-write for implementation; never danger-full-access without an explicit user ask |
-o <file> |
Always. Only the final message lands there; raw stdout echoes the whole session |
--json |
Optional: full JSONL event stream when a transcript must be parsed |
-m |
gpt-6-luna at max effort for sweeps, implementation, review; gpt-6-sol at high for root-cause hunts and design forks. Full slugs only |
Follow-ups keep context on the Codex side:
codex exec resume <session-id> "<prompt>" (or --last for the newest session).
Workflows
1. Review a diff
codex exec -m gpt-6-sol -c model_reasoning_effort="high" --sandbox read-only \
-C /abs/repo -o /tmp/codex-review.md \
"Review the git diff of unstaged changes for <FOCUS>. Run: git diff <FILE1> <FILE2>. <SPECIFIC QUESTIONS>. Answer under 400 words as a path:line list."
The prompt must name the exact git diff command with explicit file paths, the specific
questions to answer, and what changed and why.
2. Execute a written plan
Inline the FULL plan text into the prompt. Never pass a plan path: Codex cannot read
files outside its -C directory. Sandbox workspace-write.
3. General task in a repo
Fully self-contained prompt (paths, context, constraints), workspace-write, one -o
file. Have Codex end its final message with DONE: <what changed> so completion is
verifiable from the file without re-reading the session.
After dispatching
- Read the
-o file; summarize findings or changes for the user.
- Flag errors, blocked files, or missing context immediately.
- Report "done" only when Codex's final message confirms completion, not merely that
the session started.
Parallel fan-out
N background codex exec processes; nothing serializes them. One -o file per job.
Error recovery
- Wrong repo or missing directory: fix
-C.
- Reply references files outside the repo: the prompt was not self-contained; inline
the content and rerun.
- HTTP 400 naming the model: full slug required (
gpt-6-luna, not luna). Both
model-id traps are documented in ~/.claude/references/codex-delegation.md.
- Stuck or empty output: retry with a tighter prompt or split the task.
1---2name: codex-exec3version: 1.0.04tags: [codex, delegation, cli, subscription-billing]5status: draft6author: CFN Team7description: >8 Dispatch tasks to Codex via the codex exec CLI (codex-cli 0.156+; the codex MCP server9 was removed in 0.156.1). Use when asking Codex to review Claude's code changes (git10 diff, unstaged changes, regressions), to execute an implementation plan Claude wrote,11 or to run any self-contained task inside a specific repo. Triggers on "get Codex to12 review", "have Codex implement", "send this to Codex", "ask Codex to execute the13 plan", "codex delegate". GATED: only in projects whose CLAUDE.md contains a literal14 codex=true line.15dependencies: [codex-cli >= 0.156]16created: 2026-09-2417updated: 2026-09-2418complexity: Low19keywords: [codex, exec, delegate, review, implement, gpt-6]20metadata:21 source: https://skillmd.com/skills/masharratt/codex-exec22---2324# Skill: codex-exec2526## Purpose2728Dispatch work to Codex through `codex exec` with correct flags, model, and output29bounding every time. Replaces the MCP-era `codex-dispatch` plugin skill, which is dead30since `codex mcp-server` was removed in codex-cli 0.156.1.3132## Gate (all three, every call)33341. Target project CLAUDE.md contains a literal `codex=true` line. Otherwise never call35 codex.362. `OPENAI_API_KEY` unset (subscription billing; set = silent API billing).373. codex-cli 0.156+ (`codex --version`); gpt-6-* slugs 400 on older builds.3839## Inputs4041- Task description or diff focus, plus the absolute path of the target repo.4243## Outputs4445- Codex final message in the `-o <file>` file. Exit code 0 = the session ran to46 completion; still read the file to see whether Codex finished the task or stalled.4748## Call shape4950```bash51codex exec -m gpt-6-luna -c model_reasoning_effort="max" \52 --sandbox read-only -C /abs/target/repo -o /tmp/codex-answer.md "<prompt>"53```5455| Flag | Rule |56|------|------|57| `-C` | Absolute path of the TARGET repo, never the plan or workspace location |58| `--sandbox` | `read-only` for review and research, `workspace-write` for implementation; never `danger-full-access` without an explicit user ask |59| `-o <file>` | Always. Only the final message lands there; raw stdout echoes the whole session |60| `--json` | Optional: full JSONL event stream when a transcript must be parsed |61| `-m` | `gpt-6-luna` at `max` effort for sweeps, implementation, review; `gpt-6-sol` at `high` for root-cause hunts and design forks. Full slugs only |6263Follow-ups keep context on the Codex side:64`codex exec resume <session-id> "<prompt>"` (or `--last` for the newest session).6566## Workflows6768### 1. Review a diff6970```bash71codex exec -m gpt-6-sol -c model_reasoning_effort="high" --sandbox read-only \72 -C /abs/repo -o /tmp/codex-review.md \73 "Review the git diff of unstaged changes for <FOCUS>. Run: git diff <FILE1> <FILE2>. <SPECIFIC QUESTIONS>. Answer under 400 words as a path:line list."74```7576The prompt must name the exact git diff command with explicit file paths, the specific77questions to answer, and what changed and why.7879### 2. Execute a written plan8081Inline the FULL plan text into the prompt. Never pass a plan path: Codex cannot read82files outside its `-C` directory. Sandbox `workspace-write`.8384### 3. General task in a repo8586Fully self-contained prompt (paths, context, constraints), `workspace-write`, one `-o`87file. Have Codex end its final message with `DONE: <what changed>` so completion is88verifiable from the file without re-reading the session.8990## After dispatching91921. Read the `-o` file; summarize findings or changes for the user.932. Flag errors, blocked files, or missing context immediately.943. Report "done" only when Codex's final message confirms completion, not merely that95 the session started.9697## Parallel fan-out9899N background `codex exec` processes; nothing serializes them. One `-o` file per job.100101## Error recovery102103- Wrong repo or missing directory: fix `-C`.104- Reply references files outside the repo: the prompt was not self-contained; inline105 the content and rerun.106- HTTP 400 naming the model: full slug required (`gpt-6-luna`, not `luna`). Both107 model-id traps are documented in `~/.claude/references/codex-delegation.md`.108- Stuck or empty output: retry with a tighter prompt or split the task.