Codex

Codex

Concept of the skill

What it is: Codex is OpenAI's terminal-first agent harness that drives a frontier GPT model (the GPT-5.5 generation). It is the GPT-running counterpart to Claude Code, with its own differentiators: resumable sessions, non-interactive exec piping, sandbox permission modes, MCP, on-demand subagents, and a /review code-review agent.

Mental model: Same harness-vs-model split as any agent CLI — Codex is the body, a frontier GPT is the brain. What makes Codex distinct among bodies is statefulness: a session is a durable object holding transcript, plan, and approvals that you can resume by ID, plus an exec mode that pipes results to stdout for scripting and in-process dispatch.

Why it exists: To operate a codebase with a GPT model under a controllable permission boundary, while making runs resumable and scriptable — so a long task can be continued across invocations (keeping its plan and approval history) and automated into pipelines instead of restarting cold every time.

What it is NOT: It is not the GPT model itself (the model is selectable inside Codex via /model), not the OpenAI SDK/API, and not the Claude Code harness — choosing Codex is a harness decision distinct from the GPT-vs-Claude model-routing decision.

Adjacent concepts: Claude Code (the rival harness), gpt-5-5 (the model-routing decision for the GPT the harness runs), the OpenAI API (the SDK surface), and generic resumable-loop patterns (the topology underneath).

One-line analogy: Codex is a cockpit with a flight recorder and autopilot resume — you can land, walk away, and later climb back into the exact same flight with its plan and clearances intact.

Common misconception: That resuming a Codex session means re-pasting context into a fresh run. It does not — codex exec resume <SESSION_ID> reuses the stored transcript, plan, and approvals; cold one-shots that re-send full context every turn waste tokens and discard that state.

Coverage

• The harness-selection decision: when to run a piece of work in the Codex CLI versus the Claude Code harness
• Scoping work to Codex's native capabilities: resumable codex exec resume sessions, non-interactive exec stdout-piping, in-process dispatch, /permissions sandbox modes, MCP connectors, on-demand subagents, the /review code-review agent, /model switching
• The threaded-consultation pattern: holding a session across turns by capturing and resuming a session id instead of cold one-shots
• The known failure modes to avoid: non-autonomous subagents, Full-Access network/cross-machine reach, and cold-one-shot context/plan loss
• The boundary against adjacent skills: GPT-vs-Claude model routing (the model, not the harness), the rival Claude Code harness, the OpenAI/Anthropic SDK surface, and generic resumable-loop design
• What this skill is NOT: the GPT model itself, the OpenAI SDK/API, or the Claude Code harness

Philosophy of the skill

The harness and the model are two separate decisions, and conflating them is the most common error this skill guards against. Choosing Codex is a statement about the body — its statefulness, scriptability, permission boundary, and operating surface — not about the brain it happens to run; the model is selectable inside it. The opinionated stance is that statefulness is the differentiator worth optimizing for: a session that durably holds transcript, plan, and approvals turns long multi-step work from a sequence of cold restarts into one continuable flow, and an exec mode that pipes to stdout turns an interactive agent into a scriptable pipeline component. The corollary discipline is to treat the harness's powerful modes as boundaries, not conveniences — Full Access is a deliberate escalation, subagents are an explicit request, and a resume is always preferred over re-priming.

When to use Codex (routing decision)

Reach for Codex when the task wants its statefulness, scriptability, or GPT lane, and the work lives in a real repo:

Want this	Why Codex fits
Continue a prior run keeping its plan + approvals	Resumable sessions — codex resume / codex exec resume <ID>
A scripted, threaded, automatable GPT consultation	exec stdout-piping + resume-by-id (the threaded-consultation pattern)
In-process GPT dispatch (vs a visible external spawn)	exec powers in-process dispatch (e.g. the codex:codex-rescue subagent)
A controllable permission boundary	/permissions — Auto / Read-only / Full Access
A dedicated diff review pass	/review — prioritized, actionable findings
Real CLI/terminal-heavy iteration	The GPT it runs leads Terminal-Bench 2.0 (82.7%)

Choose Claude Code instead when the task wants Claude Code's richer native extensibility, plan mode, or Opus's architecture edge — see the boundary table.

Capability surface

Feature	What it gives you	When it earns its keep
codex resume / exec resume <ID> / --last / --all	Resume a session by id/most-recent, across any dir	Multi-step work continued without re-priming context
exec (non-interactive)	Pipes final plan + results to stdout	Scripting, pipelines, in-process dispatch
/permissions (Auto / Read-only / Full Access)	Sandbox boundary for the agent's actions	Gating destructive or networked actions
MCP (~/.codex/config.toml, codex mcp)	External tool/data connectors	Capabilities with no native CLI
Subagents ([agents] in config)	Parallel sub-work — explicit request only	Fan-out you deliberately invoke (never assume auto)
/review	Dedicated diff-review agent	A focused review pass with ranked findings
/model	Switch GPT model / reasoning level mid-session	Tuning the model/effort to the task
--cd / --add-dir	Steer the environment before resuming	Pointing a resumed run at the right roots

Strengths and weaknesses

Strengths

• Durable, resumable sessions that retain transcript, plan, and approvals — uniquely strong for threaded, multi-step GPT work.
• exec stdout-piping makes it scriptable and dispatchable in-process.
• Runs a GPT that leads Terminal-Bench 2.0 — well-matched to its CLI operating surface.
• Explicit sandbox modes give a clear permission boundary.

Weaknesses / failure modes

• Subagents are not autonomous — Codex only spawns them when explicitly asked; do not assume automatic fan-out.
• Full Access opens network + cross-machine reach — a real safety boundary; default to Auto/Read-only and escalate deliberately.
• Cold one-shots lose state — re-sending full context instead of exec resume <ID> wastes tokens and discards the plan/approval history.
• Its GPT trails Claude Opus on complex multi-file resolution and broad architecture (a model fact that bleeds into harness choice for those task shapes).

Verification

Use this checklist to confirm a Codex harness decision is correct and current.

• The decision was framed as a HARNESS choice (statefulness, scriptability, permission boundary, operating surface) — not as a model-routing decision in disguise
• For continued work, a resumable session (codex resume / codex exec resume <ID> / --last) is used instead of a cold one-shot that re-pastes context
• For automation/pipelines, the non-interactive exec (stdout-piping) path is used rather than the interactive TUI
• The permission mode was chosen deliberately: Auto/Read-only by default, Full Access only when network/cross-machine reach is genuinely required and its risk is accepted
• Subagent fan-out, if expected, is explicitly requested — the harness does NOT spawn subagents autonomously
• Command names, flags, and the served GPT generation were re-checked against current provider docs (the CLI ships features fast) before relying on a specific detail

Do NOT Use When

Instead of codex	Use	Why
Deciding whether GPT-5.5 or Claude should do the task	gpt-5-5	That is a MODEL-routing decision, orthogonal to the harness
Choosing/scoping the Claude Code harness	claude-code	The rival-harness decision
Writing code against the OpenAI/Anthropic API	claude-api (Anthropic) or the OpenAI SDK directly	That is application code, not harness selection
Designing a generic resumable/supervised agent loop	autonomous-loop-patterns	Loop topology below any specific harness

References

• references/model-facts.md — verified Codex capability + failure-mode facts (2026-06-08) with sources
• Sibling skills claude-code (the rival harness) and gpt-5-5 (the GPT model-routing decision this harness choice defers to)