| name | codex |
| description | Hand a task to the OpenAI Codex harness (gpt-5.5, on the ChatGPT subscription — no API key) to WORK THROUGH — answer it, or actually implement it with write access — not just review. Cross-model execution, complementary to Claude. Use when the user types /codex, says "hand this to Codex", "have Codex implement/do X", "delegate to Codex", "codex, work through this", or wants GPT-5.5 to execute a well-specified task. For adversarial code/plan REVIEW use /review or /premortem (those already call Codex read-only); this skill is for getting work DONE. |
/codex — Delegate a task to the Codex harness (gpt-5.5)
Hands an arbitrary request to OpenAI Codex on Dave's ChatGPT subscription (never an API key) to work through it. A different training family (GPT-5.5) executing the task gives cross-model leverage — Theo's "let Codex do the well-spec'd execution, keep Claude for orchestration" pattern, realized in CCv3. The read-only codex-adversary reviewer is untouched; this is its write-capable sibling.
Roster position (Game Plan): Codex's primary roles are reviewer and fixer — deep review via codex-adversary, fix patches via --implement scoped to booth findings. For milestone building, Grok is the default builder (/grok --implement); Codex builds only as failover (Grok dead/quota-capped/hung) or when the human explicitly overrides with --builder codex for a specialized milestone. A failover-built milestone is then graded by Claude critics, never by Codex itself. Doctrine: .workroom/PROTOCOL.md.
Safety contract: .claude/rules/codex-worker-safety.md (confirm-first, sandbox-is-the-boundary, worktree isolation, review-gate). Engine: the codex-worker agent. Cross-model review convention: .claude/rules/codex-adversarial.md.
When to Use
/codex <request> — explicit invocation (primary path)- "hand this to Codex", "have Codex implement …", "delegate this to Codex", "codex, work through …"
- You want GPT-5.5 to actually DO a well-specified task — fix patches, focused refactors, scripts, analysis. For workroom milestone builds, default to
/grok --implement (Grok is the rostered builder); reach for /codex --implement as failover or explicit --builder codex override
- NOT for code/plan review as a workflow → use
/review / /premortem (they already run Codex read-only); --review below is the one-off alias
Modes
| Mode | Invoke | Sandbox | Confirm? | Default effort | Writes land where |
|---|
| ask (default) | /codex <question> | read-only | no | xhigh | nowhere (answer only) |
| implement | /codex --implement <task> | workspace-write | yes (unless --yes) | high | isolated git worktree → you review the diff → apply/discard |
| resume | /codex --resume <followup> | inherits | yes | inherits | same worktree/thread |
| review (alias) | /codex --review [base] | read-only | no | xhigh | delegates to codex-adversary unchanged |
Flags: --model gpt-5.5|gpt-5.6-sol|gpt-5.6-terra|gpt-5.6-luna|gpt-5.4|gpt-5.4-mini (default gpt-5.5; 5.6 family live-verified 2026-07-11 on codex-cli 0.144.1; any -codex or fabricated id is rejected — it 400s on the subscription). --effort low|medium|high|xhigh (5.6 models additionally accept max|ultra; ultra auto-delegates — unprobed, avoid unattended). --yes (skip the interactive confirm for orchestrator/Ralph use — still sandboxed, still logged, still produces a reviewable patch). --complex (multi_agent fan-out for genuinely BROAD ask/implement tasks — opt-in; requires ~/.codex/agents/explorer.toml pinned to gpt-5.5 or it refuses; ~1,940 tok/call + fan-out latency; NOT re-applied on resume).
Execution
ask / implement / resume → spawn codex-worker
Task(
subagent_type="codex-worker",
prompt="""
## Mode
ask | implement | resume
## Request
[the user's task, verbatim + any clarifying context]
## Model
gpt-5.5
## Effort
[xhigh for ask, high for implement — or the user's --effort]
## Autonomy
confirm # or "yes" if the user passed --yes
## Complex
false # or "true" if the user passed --complex (multi_agent fan-out; ask/implement only)
## Scope # resume only — the Codex session id (UUID) from the implement run's summary
<SESSION_ID> # leave EMPTY to fall back to --last (do NOT pass the literal "last")
## Worktree # resume only — the worktree path from the implement run's summary
<path>
## Codebase
$CLAUDE_PROJECT_DIR
"""
)
For implement, the worker will surface the exact command + target worktree and (unless --yes) wait for your explicit go-ahead, run Codex with workspace-write inside a throwaway worktree, independently git diff the result, and show you the patch before anything touches your live working tree. Present that diff to the user; on approval the worker applies it, otherwise it discards and removes the worktree. The worker also returns the Codex session id and worktree path — pass both back on a later --resume so it continues the exact thread (robust under concurrency, unlike --last).
--review → delegate to the existing reviewer
Task(
subagent_type="codex-adversary",
prompt="""
## Mode
code
## Scope
base ref: [BASE_REF, default main]
## Codebase
$CLAUDE_PROJECT_DIR
"""
)
/codex --review is a convenience alias so users have one mental entry point (/codex) — it reuses codex-adversary's carefully-tuned read-only flags, it does NOT reimplement review.
Guardrails (summary — full text in .claude/rules/codex-worker-safety.md)
- Subscription only. The worker asserts
codex login status = "Logged in using ChatGPT" and strips OPENAI_API_KEY/CODEX_API_KEY from Codex's env. Fails loud, never silently uses an API key.
- Confirm-first for
implement/resume (the only approval gate — codex exec has none). --yes skips only the interactive pause.
- Worktree isolation by default — write runs happen in a throwaway git worktree outside the repo (sibling
../.codex-worktrees/<repo>-<ts>-<pid>), never in-place, so they can't collide with your live session or the file_claims DB. (An --in-place mode was considered and dropped in v2 — worktree isolation is the retained safety win.)
- Auto worktree GC — before each implement run, stale clean worktree dirs (~190MB each) older than
$CODEX_WT_GC_DAYS (default 7d) are reclaimed; a worktree with unreviewed (dirty) changes is never touched, so a dormant awaiting-resume one is safe. Manual sweep: scripts/codex/gc-worktrees.sh.
- Review-gate — never auto-commits/auto-merges; produces a patch you approve first.
- Model allowlist —
gpt-5.6-sol/gpt-5.6-terra/gpt-5.6-luna/gpt-5.5/gpt-5.4/gpt-5.4-mini only (live-probed 2026-07-11).
- No hook can see inside Codex's sandbox — enforcement is
--sandbox + this preflight, not any Claude Code hook.
- Usage-limit aware — if the ChatGPT subscription quota is exhausted,
/codex returns a clean "usage limit hit; resets ~" message (never a fabricated result) and logs usage_limited:true. Detection is reactive — the subscription exposes no queryable quota surface to preflight.
--complex is gated — multi_agent fan-out (ask/implement) runs only after asserting ~/.codex/agents/explorer.toml pins gpt-5.5 (prevents the gpt-4.1 role-fallback 400); opt-in, never default, with a standing Windows re-probe caveat (openai/codex#19399).
Examples
User: /codex how does the report-registry upsert dedupe by Run ID?
→ ask mode, read-only. Returns GPT-5.5's answer sourced from the clean -o capture. No confirm, no writes.
User: /codex --implement add a --limit flag to scripts/report-registry/query.mjs
→ implement mode. Shows the codex exec command + worktree path, waits for your OK,
runs Codex with workspace-write in an isolated worktree, shows you the diff,
applies it to your working tree on approval. Logs a telemetry row.
User: /codex --implement --complex refactor the report-registry pipeline end-to-end
→ implement + multi_agent fan-out (explorer/worker sub-agents on gpt-5.5). Asserts
~/.codex/agents/explorer.toml is pinned to gpt-5.5 first, prints the #19399 re-probe
caveat, then the usual worktree + diff-review flow. For genuinely BROAD tasks; costs
extra tokens + latency. Refuses if the explorer pin is missing.
User: /codex --resume also add a test for the new flag
→ continues the same Codex thread + worktree.
User: /codex --review main
→ runs the standard cross-model adversarial review (codex-adversary), read-only.
Telemetry
One row per run → .claude/logs/codex-worker.jsonl (schema: .claude/logs/codex-worker.README.md). Distinct from codex-lift.jsonl (that logs review lift counts; this logs task execution).
