# Codex Delegate > 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. - Skill: `ai-zixun/codex-delegate` (Agent Skill, multi-file: 9 files) - Install (CLI): `npx skillmds@latest add ai-zixun/codex-delegate` - Raw SKILL.md: https://api.skillmd.com/api/skills/ai-zixun/codex-delegate/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: ai-zixun (https://skillmd.com/u/ai-zixun) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/ai-zixun/codex-delegate --- # 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: ```bash "${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.`: - `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: ```bash "${CLAUDE_PLUGIN_ROOT:-.}/skills/codex-delegate/scripts/codex-learn.sh" log '{"task":"","category":"","decision":"delegate","risk":"low","reason":""}' ``` **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: ```bash "${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 ` 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): ```bash "${CLAUDE_PLUGIN_ROOT:-.}/skills/codex-delegate/scripts/codex-run.sh" [options] "" ``` Pick the mode by what you need back: - **Implement (write):** `codex-run.sh --write --effort high ""` — 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 ""`. - **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: ```bash "${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 "" ""` 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: ```bash "${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 `` and an output/completion contract; add verification, grounding, and scope blocks per task type. Minimal implementation prompt: ```xml Migrate every call site of `oldApi(x, y)` to `newApi({x, y})` across src/. Preserve behavior. Update ALL call sites, not just the first few. Update imports. Leave the tree building. Before finishing, run the test suite (or typecheck) and confirm it passes. Fix what you broke. Keep changes scoped to this migration. No unrelated refactors, renames, or reformatting. ``` 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`.