codex-delegate

name	codex-delegate
description	Route eligible coding work to OpenAI Codex (GPT-5) to save cost and time while Claude stays orchestrator and quality gate. Use PROACTIVELY when a task is well-specified and bulk, mechanical, repetitive, parallelizable, or long-running — codemods, boilerplate, migrations, wide find-and-replace refactors, test scaffolding, dependency bumps, sweeping a change across many files — or when an independent second-model review, diagnosis, or research pass adds value. Also triggers on explicit asks to delegate to Codex, offload work, or use Codex for a task. Do NOT use for interactive debugging, architecture and design judgment, nuanced or high-stakes code, or work that depends on rich in-conversation context.
allowed-tools	["Bash","Read","Grep","Glob","Edit","Write"]

Codex Delegate

Route work Claude could do but Codex does as well and more cheaply over to the codex CLI, then verify and integrate the result. Codex (GPT-5) runs at roughly half the cost of a frontier Claude model, is highly token-efficient, and sustains long unattended runs — so offloading rote, well-specified work conserves the expensive Claude budget for what Claude is uniquely good at: judgment, interactive iteration, and final quality.

Claude stays the orchestrator. You decide what to delegate, write the spec, and own the quality gate on what comes back. Codex is a fast, cheap worker — not the decision-maker.

The core decision: DELEGATE or KEEP

Ask two questions:

1. Can I specify "done" crisply enough that a fresh agent with no chat context could finish it?
2. Is the work bulk, mechanical, long-running, parallelizable, or would it benefit from an independent second model?

If both are yes → DELEGATE. Otherwise → KEEP and do it yourself.

DELEGATE to Codex ✅	KEEP on Claude 🧠
Well-specified implementation with a clear acceptance test	Ambiguous work needing back-and-forth to pin down
Bulk/repetitive edits across many files (codemods, renames, API migrations)	A single subtle change needing deep judgment
Boilerplate, scaffolding, config, fixture/test generation	Architecture & interface design decisions
Mechanical refactors that preserve behavior	Refactors requiring taste and repo-wide judgment
Long-running self-verifying tasks (make tests green, wire a pipeline)	Real-time interactive debugging / exploration
Terminal/CLI-heavy chores (build fixes, dependency bumps, tooling)	Anything gated on rich in-conversation context
Independent second-opinion review / diagnosis (cross-model diversity)	Final quality gate, user-facing writing, risky/irreversible ops

When unsure, keep it. A bad delegation costs more than it saves: you pay to specify the task, pay Codex to run, then pay Claude to verify and often redo.

Grounding for these splits: Codex leads on long-horizon autonomy, token/cost efficiency, and terminal benchmarks; Claude leads on code-quality/cleanliness and repo-level refactor judgment. See references/routing-rubric.md for the full decision guide, worked examples, and the cost model.

Routing decision protocol

For any non-trivial task, decide where it runs before you start. Resolve config once:

"${CLAUDE_PLUGIN_ROOT:-.}/skills/codex-delegate/scripts/codex-config.sh"    # merged JSON

Then walk these steps in order. Config is a hard guardrail — your judgment operates within it, never against an explicit setting.

1. Global gates.

• enabled: false → do everything yourself; stop here.
• Effective mode is manual if decisionMode: manual or autoRoute: false → only delegate when the user explicitly asks; otherwise do it yourself.
• decisionMode: config → follow step 2 categories only; treat a silent/auto category as keep (no autonomous judgment).
• decisionMode: auto (default) → full protocol below.

2. Classify + apply the category guardrail. Map the task to the closest category: bulkMechanical, migrations, boilerplate, tests, review, diagnosis, research, computerUse, architecture, interactiveDebug, highStakes. Then routing.<category>:

• keep → you do it. Stop. (Hard guardrail — never override.)
• ask → ask the user before delegating.
• delegate → eligible; continue.
• silent or auto → use judgment; continue.

3. Eligibility — the two-gate test + cost model (see the table above and references/routing-rubric.md). If it fails either gate, keep it. Also obey customRules (plain-English rules, including anything you've learned — step 6).

4. Risk assessment. Classify the candidate:

• Low-risk: read-only work (review / diagnose / research), or a scoped write that touches ≤ riskPolicy.maxAutoFiles files and no riskPolicy.protectedPaths.
• High-risk: writes touching more than maxAutoFiles, anything under protectedPaths, irreversible/outward-facing actions, or fuzzy scope.

5. Act per riskPolicy.autoDelegate.

• always → delegate now.
• lowRisk (default) → low-risk: delegate and tell the user; high-risk: ask first.
• confirm → ask before every delegation.

When you delegate, announce it in one line ("Delegating to Codex: — .") so the decision is visible. If learning.logDecisions is true, log it:

"${CLAUDE_PLUGIN_ROOT:-.}/skills/codex-delegate/scripts/codex-learn.sh" log '{"task":"<short>","category":"<cat>","decision":"delegate","risk":"low","reason":"<why>"}'

6. Learn from corrections (when learning.enabled). If the user overrides a decision — "don't send that to Codex", "always delegate migrations", "keep payments local" — persist it so you route that way next time:

"${CLAUDE_PLUGIN_ROOT:-.}/skills/codex-delegate/scripts/codex-learn.sh" rule "Never delegate anything under src/payments/."

Learned rules merge into customRules automatically on the next config resolve. Confirm what you saved in one line. Use codex-learn.sh rules / forget <n> to review or undo.

Defaults give you a hands-off but safe router: it auto-delegates confident, low-risk, reversible work (read-only reviews, scoped mechanical edits) and pauses to confirm the risky stuff (broad writes, protected paths). Tune with decisionMode and riskPolicy. Full schema: references/configuration.md.

How to delegate

All delegation goes through the wrapper (read-only by default, robust timeout and error surfacing, and a built-in filesystem-boundary preamble):

"${CLAUDE_PLUGIN_ROOT:-.}/skills/codex-delegate/scripts/codex-run.sh" [options] "<prompt>"

Pick the mode by what you need back:

• Implement (write): codex-run.sh --write --effort high "<spec>" — Codex edits files. You then review git diff as the quality gate before anything ships.
• Review / diagnose / research (read-only): default sandbox. Codex reads the repo and reports; it does not touch files.
• Big/long task: raise --timeout (default 900s) and consider --effort high. If it still times out, the task is too big for one run — split it.
• Follow-up on the same thread: codex-run.sh --resume "<delta instruction>".
• Cheaper/faster tier: --model gpt-5.3-codex-spark for simpler mechanical jobs.

Run the wrapper with the Bash tool. For long jobs, run it in the background so you can keep working, and collect the result when it finishes.

Computer use — presenting results in Mac apps

Codex/this skill can open finished work in a Mac app so the user can see it — e.g. open a built page in Chrome, a report in Pages, a PDF in Preview. Governed by computerUse in the config.

When to present (computerUse.autoPresent): viewable (default) auto-opens only when the task produced a viewable artifact; always presents after every delegation; manual only on explicit request ("show me in Chrome"). Check eligibility:

"${CLAUDE_PLUGIN_ROOT:-.}/skills/codex-delegate/scripts/codex-present.sh" --is-viewable path/to/index.html

Who opens it (computerUse.execution):

• hybrid (default) — if the artifact was produced by a task you already delegated to Codex, let Codex open it as the final step of that run (add an open -a "<App>" "<file>" instruction to the Codex prompt and run with --full-access). For a standalone "just show me this" with no active Codex run, open it inline:

  "${CLAUDE_PLUGIN_ROOT:-.}/skills/codex-delegate/scripts/codex-present.sh" build/index.html
  "${CLAUDE_PLUGIN_ROOT:-.}/skills/codex-delegate/scripts/codex-present.sh" https://localhost:3000
  

• codex — always route the open through Codex (codex-run.sh --full-access "open -a …").

• inline — always use codex-present.sh directly (fastest, most reliable).

codex-present.sh picks the app from computerUse.openers (by URL or file extension, falling back to the macOS default app). Bare open -a needs no special permission; richer scripted control (osascript) is gated behind computerUse.allowAppleScript and needs a one-time macOS Automation grant. macOS only — a no-op elsewhere.

When a delegated Codex run should present its own output, keep it in the same run (one task, ending in the open) rather than a second delegation — Codex already has the file paths in context.

Writing the Codex prompt

Codex responds to tight contracts, not conversation. State the task, what "done" looks like, and the small set of rules that matter — using XML-tagged blocks. Every prompt should carry a <task> and an output/completion contract; add verification, grounding, and scope blocks per task type.

Minimal implementation prompt:

<task>
Migrate every call site of `oldApi(x, y)` to `newApi({x, y})` across src/. Preserve behavior.
</task>
<completeness_contract>
Update ALL call sites, not just the first few. Update imports. Leave the tree building.
</completeness_contract>
<verification_loop>
Before finishing, run the test suite (or typecheck) and confirm it passes. Fix what you broke.
</verification_loop>
<action_safety>
Keep changes scoped to this migration. No unrelated refactors, renames, or reformatting.
</action_safety>

Copy the closest starting point from references/prompt-recipes.md (diagnosis, narrow fix, bulk implementation, review, research) and trim. Anti-pattern to avoid: vague "take a look and let me know" prompts with no output contract — they waste the run.

Handling what comes back

• Verify before you trust. For write tasks, read the git diff yourself — this is the whole point of keeping Claude as the gate. Confirm scope, correctness, and that nothing unrelated changed. Run the tests.
• You may reject or redo. If Codex's output is wrong or off-scope, say so plainly and either --resume with a correction or take it over yourself. Do not launder a bad Codex result into a confident answer.
• For review/diagnosis output, preserve Codex's findings, severity ordering, and evidence. Keep any "this is an inference / unverified" markers Codex made. Present it as an independent second opinion, and compare against your own view when useful.
• Attribution. Tell the user when work was done by Codex and what you verified — e.g. "Codex applied the migration across 14 files; I reviewed the diff and ran the tests (green)."
• Never auto-apply fixes from a review. If Codex reviewed code and suggested changes, surface them and let the user choose — don't silently implement them.

Safety

• Read-only is the default. Only pass --write for tasks you intend to verify.
• The wrapper prepends a boundary keeping Codex out of ~/.claude/, ~/.codex/, and agent/skill definition files. Keep it.
• Delegating sends repository code to OpenAI. Don't delegate work involving secrets or code the user has said must not leave the environment. When in doubt, ask.
• One task per run. Split unrelated asks into separate delegations.

Prerequisites

Needs the codex CLI installed and authenticated (codex login, or OPENAI_API_KEY). The wrapper prints install/auth guidance if it's missing. See references/setup.md.