> **Update (2026-07-09, second revision):** After a live delegation shakedown, the wrapper now emits a one-line provenance record (`codex-delegate: mode=… model=… effort=…`) to stderr on success — falling back to the `~/.codex/config.toml` default when `--model` isn't passed — so the orchestrator can attribute results to the model actually used without reading the Codex config. The embedded wrapper below has also been synced wholesale to the successor's current revision — adding the `--network` flag for write mode and hardened argument parsing (a missing option value now prints usage instead of dying silently) — so installing from this gist yields the same script as the successor plan.
>
> **Update (2026-07-09):** Fixed for how non-interactive `codex exec` actually behaves (verified against codex-cli 0.142.5): write mode previously used `approval_policy="on-request"` plus `approvals_reviewer="auto_review"`, but non-interactive runs have no surface to answer approval prompts (requests fail) and `approvals_reviewer` is not a documented config key — all modes now use `approval_policy="never"`, with safety coming from the sandbox tier. Also fixed: write-mode prompts no longer contain a contradictory "do not edit files" rule; the wrapper now handles non-git directories (`--skip-git-repo-check` for research/patch, and write mode requires git so the diff is reviewable and reversible); and `--effort` accepts the full `minimal|low|medium|high|xhigh` range and is only sent to Codex when explicitly passed, so `~/.codex/config.toml` defaults are respected. A fuller successor setup lives at https://gist.github.com/christophermark/50e0487fce92d7de176bdc8bb5c8ea5e
You are editing my personal Claude Code and Codex config.
Goal: recreate the Codex delegation setup exactly.
Files to edit/create:
- `~/.claude/CLAUDE.md`
- `~/.claude/skills/delegate-to-codex/SKILL.md`
- `~/.claude/skills/delegate-to-codex/scripts/codex-delegate.sh`
- `~/.codex/agents/researcher.toml`
- `~/.codex/agents/implementer.toml`
Do not rewrite or “improve” the text. Use the content below verbatim.
## 1. Add this Codex paragraph to `~/.claude/CLAUDE.md`
Place it after the general delegation bullets and before the final “personal default” note:
```md
When a delegated task is large enough that a Claude subagent is the wrong cost/context tradeoff, use the `delegate-to-codex` skill to hand a frozen work order to Codex. Default to read-only Codex runs for research or patch drafting; use Codex write mode only for bounded implementation work where the approach and scope are clear. Keep final judgment, diff review, verification, commits, pushes, releases, secrets, destructive operations, and MCP-only tasks in Claude.
```
## 2. Create `~/.claude/skills/delegate-to-codex/SKILL.md`
`````md
---
name: delegate-to-codex
description: Use when Claude Code should delegate large read-heavy work, patch drafting, mechanical implementation planning, refactors, bug-fix investigation, test-writing plans, or codebase exploration to Codex CLI while Claude keeps design, review, and verification.
---
# Delegate To Codex
Use this skill only from Claude Code. Do not use it from Codex, and never ask Codex to delegate back to Claude or to another Codex run.
Use Codex when the task is a bounded work order that would otherwise spend a lot of Claude context on file reading, migration mechanics, patch drafting, or repetitive analysis. Keep the task in Claude when the hard part is product judgment, architecture, naming, UX, release decisions, secrets, MCP-only tools, destructive operations, commits, pushes, or final review.
Prefer read-only delegation for research and patch drafting. Use write delegation only when the implementation scope is narrow, the approach is already decided, and Codex can safely edit inside the target workspace. Write delegation uses `--sandbox workspace-write` with `approval_policy="never"`: non-interactive `codex exec` has no surface to answer approval prompts, so safety comes from the sandbox, not from approvals. Write mode also requires the target to be a git repository so the resulting diff is reviewable and reversible.
## Routing
Delegate to Codex for:
- Large read-only codebase exploration with a narrow question.
- Mechanical refactors or migrations after Claude has frozen the approach.
- Bug investigations with a known symptom or failing test.
- Patch drafting where Claude will review and apply the patch.
- Test coverage suggestions or test patch drafting with exact target files.
Do not delegate:
- Ambiguous design where writing the spec is the real work.
- Tiny edits where delegation overhead is larger than the task.
- Secrets, credentials, 1Password, production access, releases, deploys, GitHub mutations, commits, or pushes.
- Browser, computer-use, or MCP-only workflows available only in the Claude session.
- Final review or verification of Codex output.
## Work Order Contract
Before invoking Codex, write a complete prompt in a temp file. Codex starts with no Claude session context, so include:
- Goal and success criteria.
- Absolute repo path and any important working directory constraints.
- Relevant files, symbols, logs, or commands already known.
- Constraints and non-goals, including files not to touch.
- Expected proof, such as an exact test command or "no commands needed."
- Output shape.
For research mode, require a concise answer with paths, symbols, evidence, confidence, and unresolved questions.
For patch mode, require a unified diff only after the analysis, plus a short explanation and verification notes. Tell Codex explicitly not to edit files because it is running in a read-only sandbox.
For write mode, require Codex to edit only the scoped files needed for the task, run focused verification when available, and report the final diff summary plus commands run. Claude still reviews the resulting diff before any commit, push, release, or closeout.
## Invocation
Prefer the bundled wrapper instead of hand-writing `codex exec` commands:
```bash
/Users/chris/.claude/skills/delegate-to-codex/scripts/codex-delegate.sh \
--repo /absolute/path/to/repo \
--mode research \
--prompt-file /path/to/work-order.md \
--output /tmp/codex-delegate.md
```
Patch drafting:
```bash
/Users/chris/.claude/skills/delegate-to-codex/scripts/codex-delegate.sh \
--repo /absolute/path/to/repo \
--mode patch \
--prompt-file /path/to/work-order.md \
--output /tmp/codex-patch.md
```
Bounded implementation with direct Codex edits:
```bash
/Users/chris/.claude/skills/delegate-to-codex/scripts/codex-delegate.sh \
--repo /absolute/path/to/repo \
--mode write \
--prompt-file /path/to/work-order.md \
--output /tmp/codex-write.md
```
The wrapper uses:
- `codex exec --cd <repo>` to run in the target repository.
- `--sandbox read-only` for research and patch drafting; `--sandbox workspace-write` for write mode.
- `approval_policy="never"` in every mode, because non-interactive runs cannot answer approval prompts; the sandbox is the safety boundary.
- `--skip-git-repo-check` automatically when the target isn't a git repository (research and patch only; write mode refuses to run without git).
- `--output-last-message <file>` so Claude reads the final response from a file.
- `model_reasoning_effort` override when requested.
Do not use `--yolo`, `--dangerously-bypass-approvals-and-sandbox`, or `danger-full-access`.
## Review And Integrate
After Codex returns:
1. Read the output file.
2. If Codex returned research, verify important claims against the source files before relying on them.
3. If Codex returned a patch, inspect it like a pull request before applying anything.
4. If Codex edited files in write mode, inspect the full diff and run or re-run focused verification before trusting it.
5. Apply changes manually with normal Claude editing tools when patch mode is used.
6. If Codex needs one follow-up, create a new precise work order. After two poor rounds, stop delegating and take over directly.
Close out as Claude: summarize what changed, cite local files, and report verification.#!/usr/bin/env bash
set -euo pipefail
usage() {
cat <<'USAGE'
Usage: codex-delegate.sh --repo PATH --prompt-file FILE [--output FILE]
[--mode research|patch|write] [--model MODEL]
[--effort minimal|low|medium|high|xhigh] [--network]
Runs Codex CLI non-interactively and writes its final response to the output file.
research/patch modes run in a read-only sandbox; write mode uses workspace-write
and requires the target to be a git repository. --network enables outbound network
access inside the write sandbox (ignored in other modes). --effort overrides the
Codex config's model_reasoning_effort; when omitted, the config default applies.
On success, prints a provenance line (mode/model/effort) to stderr and the
output file path to stdout.
USAGE
}
repo="" prompt_file="" output_file="" mode="research" model="" effort="" network=0
while [[ $# -gt 0 ]]; do
case "$1" in
--repo) repo="${2:-}"; shift 2 || { usage >&2; exit 2; } ;;
--prompt-file) prompt_file="${2:-}"; shift 2 || { usage >&2; exit 2; } ;;
--output) output_file="${2:-}"; shift 2 || { usage >&2; exit 2; } ;;
--mode) mode="${2:-}"; shift 2 || { usage >&2; exit 2; } ;;
--model) model="${2:-}"; shift 2 || { usage >&2; exit 2; } ;;
--effort) effort="${2:-}"; shift 2 || { usage >&2; exit 2; } ;;
--network) network=1; shift ;;
-h|--help) usage; exit 0 ;;
*) echo "Unknown argument: $1" >&2; usage >&2; exit 2 ;;
esac
done
[[ -n "$repo" && -n "$prompt_file" ]] || { usage >&2; exit 2; }
[[ -d "$repo" ]] || { echo "Repo not found: $repo" >&2; exit 2; }
[[ -f "$prompt_file" ]] || { echo "Prompt file not found: $prompt_file" >&2; exit 2; }
case "$mode" in research|patch|write) ;; *) echo "--mode must be research, patch, or write" >&2; exit 2 ;; esac
case "$effort" in ""|minimal|low|medium|high|xhigh) ;; *) echo "--effort must be minimal, low, medium, high, or xhigh" >&2; exit 2 ;; esac
command -v codex >/dev/null 2>&1 || { echo "codex CLI not found on PATH" >&2; exit 127; }
git_repo=0
git -C "$repo" rev-parse --is-inside-work-tree >/dev/null 2>&1 && git_repo=1
if [[ "$mode" == "write" && "$git_repo" -ne 1 ]]; then
echo "write mode requires a git repository (the diff must be reviewable and reversible): $repo" >&2
exit 2
fi
[[ -n "$output_file" ]] || output_file="$(mktemp "${TMPDIR:-/tmp}/codex-delegate.XXXXXX.md")"
combined_prompt="$(mktemp "${TMPDIR:-/tmp}/codex-work-order.XXXXXX.md")"
stderr_file="$(mktemp "${TMPDIR:-/tmp}/codex-delegate-stderr.XXXXXX.log")"
trap 'rm -f "$combined_prompt" "$stderr_file"' EXIT
{
echo "# Delegated Work Order"
echo
cat "$prompt_file"
echo
echo "# Delegation Rules"
echo
echo "- Keep the response concise and evidence-backed; lead with the answer."
echo "- Report commands you ran (or would run) and summarize their results."
case "$mode" in
research)
echo "- You are in a read-only sandbox. Do not edit files."
echo "- Return: answer, paths/symbols with short evidence, confidence, open questions."
;;
patch)
echo "- You are in a read-only sandbox. Do not edit files."
echo "- Return a proposed unified diff for any code changes, then a short"
echo " explanation and verification notes. Do not claim files were changed;"
echo " the caller will review and apply any accepted patch."
;;
write)
echo "- You may edit files inside this workspace, strictly within the requested scope."
echo "- Run focused verification when available."
echo "- Do not run git commit/push or any destructive command."
echo "- Return: files changed, commands run, verification results, risks."
;;
esac
} > "$combined_prompt"
sandbox_mode="read-only"
[[ "$mode" == "write" ]] && sandbox_mode="workspace-write"
args=(
exec
--cd "$repo"
--sandbox "$sandbox_mode"
-c 'approval_policy="never"'
--output-last-message "$output_file"
)
[[ -n "$effort" ]] && args+=(-c "model_reasoning_effort=\"$effort\"")
[[ "$git_repo" -eq 1 ]] || args+=(--skip-git-repo-check)
[[ "$mode" == "write" && "$network" -eq 1 ]] && args+=(-c 'sandbox_workspace_write.network_access=true')
[[ -n "$model" ]] && args+=(--model "$model")
if [[ "${CODEX_DELEGATE_DEBUG:-}" == "1" ]]; then
codex "${args[@]}" - < "$combined_prompt"
else
if ! codex "${args[@]}" - < "$combined_prompt" 2>"$stderr_file"; then
echo "Codex delegation failed. Stderr (first 120 lines):" >&2
sed -n '1,120p' "$stderr_file" >&2
exit 1
fi
fi
if [[ -z "$model" ]]; then
model="$(sed -n 's/^model[[:space:]]*=[[:space:]]*"\(.*\)"/\1/p' "$HOME/.codex/config.toml" 2>/dev/null | head -1)"
model="${model:-unknown} (config default)"
fi
if [[ -z "$effort" ]]; then
effort="$(sed -n 's/^model_reasoning_effort[[:space:]]*=[[:space:]]*"\(.*\)"/\1/p' "$HOME/.codex/config.toml" 2>/dev/null | head -1)"
effort="${effort:-unknown} (config default)"
fi
echo "codex-delegate: mode=$mode model=$model effort=$effort" >&2
echo "$output_file"Then make the script executable:
chmod +x ~/.claude/skills/delegate-to-codex/scripts/codex-delegate.shCreate this directory if needed:
mkdir -p ~/.codex/agentsname = "researcher"
description = "Read-only codebase researcher for finding files, tracing symbols and call sites, checking existing patterns, and summarizing structure without editing files."
model = "gpt-5.4-mini"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
developer_instructions = """
You are a read-only research agent. Answer a specific question about a codebase and hand back a short, evidence-backed answer.
Rules:
- Never edit files or run commands with side effects.
- Keep the investigation narrow to what was asked.
- Prefer exact file paths, symbols, and short quoted evidence over broad prose.
- Use fast local search tools such as rg when available.
- If confidence is low, say what would resolve it instead of guessing.
Return:
- Answer.
- Files and symbols the answer is based on.
- Confidence.
"""name = "implementer"
description = "Implementation worker for narrow, mechanical coding tasks after the approach is decided. Makes scoped workspace edits when asked, then reports diffs and verification for review."
model = "gpt-5.5"
model_reasoning_effort = "medium"
sandbox_mode = "workspace-write"
developer_instructions = """
You are an implementation worker. The caller has already decided the approach. Execute a narrow, well-specified coding task by making scoped workspace edits and reporting verification notes.
Rules:
- Stay inside the given scope.
- Do not redesign, broaden the refactor, or add abstractions beyond the ask.
- Follow existing patterns and conventions in surrounding code.
- Make the smallest correct proposed change.
- Edit only files required for the requested task.
- If the task is ambiguous or underspecified, stop and report the ambiguity instead of guessing.
- If relevant checks exist, run focused verification commands when practical.
Return:
- One-line summary.
- Files changed and diff summary.
- Verification performed or recommended, including command results.
- Risks or follow-up.
"""Validation:
- Run
bash -n ~/.claude/skills/delegate-to-codex/scripts/codex-delegate.sh - Run
~/.claude/skills/delegate-to-codex/scripts/codex-delegate.sh --help - In Claude Code, run
/reload-skillsor restart Claude Code. - Restart Codex so it loads the new custom agents.