Codex Delegate

Codex Delegate Skill

Claude is the supervisor. Codex CLI runs the mechanical work. Claude plans, constrains scope, reviews the diff, and verifies outcomes.

Why use this instead of raw codex exec

This wrapper is not cosmetic. It exists because every shipping task that bypasses it loses one of three things that have caused real incidents:

| What the wrapper handles | What raw codex exec costs you | |---|---| | stdin closure ( 20 files needing the same edit | | **Mirror sync** (zh-TW → zh-Hans + en, 8 files) | **17-22× token reduction** | Multi-locale docs / curricula | | **Multi-file rename / typed-API migration** | ~3× (extrapolated from Phase D title-sweep) | > 10 files following one pattern | | **Single-file .result.json. Acceptance is Claude's job, not the wrapper's.

• Do not wrap the wrapper in Start-Process. Call it inline so file writes persist.

When to delegate

Mechanical → codex · Reasoning → claude · Long-context synthesis → gemini.

Full routing table and good/bad examples: references/delegation-targets.md.

Workflow

1. Brief: write .ai/codex_task_.md with Context / Goal / Constraints / Acceptance. Template: references/task-template.md. For a judgment-sensitive task (debugging, write-capable change, review, research) — where an unsupported guess or a half-finished fix would hurt — also add the XML prompt blocks from references/codex-prompt-blocks.md to the Goal/Constraints. A pure mechanical sweep does not need them. If the brief was already written by agent-task-splitter at .ai/codex_task__.md, read .coord/plan.yml for round context first.

1. Run: from Claude Code Bash, invoke the wrapper from its install location:

``bash bash ~/.claude/skills/codex-delegate/scripts/run_codex.sh \ --prompt "Read .ai/codex_task_.md and execute all instructions inside." \ --repo "$PWD" \ --log-file .ai/codex_log_.txt ` --repo defaults to the caller's $PWD; pass --repo "$PWD" explicitly only if you want to be defensive about the working directory at invocation. On non-Claude-Code agentskills.io hosts, substitute the host's skills directory (e.g. ~/.hermes/skills//codex-delegate/scripts/run_codex.sh). PowerShell variant + env vars: references/wrapper.md`.

1. Read status: cat .ai/codex_log_.txt.result.json.

• success → diff still needs review.
• fallback → Codex quota hit; Claude must take over.
• error → wrapper failed; check .error.

1. Accept: read the diff, confirm scope, run the verification commands listed in the task file. Reject if Codex drifted. Extended checklist: references/review-checklist.md.

Output contract

.result.json includes at minimum: status (success|fallback|error), delegate ("codex"), model, log_file, output_file, summary, risks, files_changed, tests_run, timestamp_utc. Full schema and status semantics: references/output-contract.md.

Compatibility

• Tested with @openai/codex 0.128.0 (May 2026). Should work with any version that accepts codex exec --sandbox workspace-write.
• Default model: gpt-5.5 (bumped from gpt-5.4 on 2026-05-14 per operator preference; override via --model or -Model). gpt-5.4 remains available and is ~3× cheaper per token if cost-sensitive — trade-offs and an A/B-test recipe live in references/model-selection.md. Other models on your CLI: see codex models.
• Wrapper calls codex exec --sandbox workspace-write -C -m . The older --full-auto flag is deprecated in 0.128+ and was replaced.
• codex exec runs in non-interactive mode and auto-approves (no --ask-for-approval flag exists on exec; that flag is top-level only).
• Direct codex exec calls must close stdin (</dev/null) to avoid the historical hang (issue #20919).
• PowerShell wrapper requires $ErrorActionPreference to NOT be Stop so stderr writes (warnings, banners) don't trip the catch block.

See also

• references/delegation-targets.md — when to use vs avoid
• references/wrapper.md — full wrapper invocation, env vars, Windows runner notes
• references/task-template.md — task brief template
• references/codex-prompt-blocks.md — XML prompt blocks + recipes + anti-patterns for judgment-sensitive briefs
• references/output-contract.md — full .result.json schema, status semantics, .fallback_claude quota sentinel
• references/review-checklist.md — extended acceptance gate
• references/patterns.md — five single-task delegation shapes (context file, parallel, resume, structured output, review mode)
• references/multi-agent.md — leaf role in router/leaves architecture; when to route through research-hub-multi-ai or agent-task-splitter
• references/examples.md — concrete invocation examples on codex-cli 0.128.0+ syntax
• references/model-selection.md — gpt-5.4 vs gpt-5.5 trade-offs (A/B-tested) + when to override the default

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: WenyuChiou
• Source: WenyuChiou/codex-delegate
• License: MIT

Install and usage instructions live in the source repository linked above.