use-codex

name	use-codex
display_name	Use Codex
description	Spawn one or more OpenAI Codex CLI subagents from bash to offload context-heavy work from the parent Claude. Use when the user says "use codex", "build with codex", "ask codex", "get a codex second opinion", "compare codex vs claude", "have two agents try it", or otherwise asks to delegate or parallelize work to Codex. Also use whenever a user asks for a large coding task — research, multi-file refactors, large codebase analysis.
builtIn	true

Codex Subagent Skill

Spawn autonomous Codex CLI subagents to offload context-heavy work. Subagents burn their own tokens and return only their final message, so the parent's context stays clean.

Golden Rule: If task + intermediate work would add 3,000+ tokens to parent context → use a subagent.

Instructions

When invoking this skill:

1. Clarify intent. Figure out what the user wants. If unclear, ask. Inline args ("use codex to review my auth plan") usually carry the intent — infer from them. Common buckets: second-opinion code review, refactor, plan validation, implementation of features, fresh perspective on a stuck bug, parallel comparison of approaches.
2. Pick model + reasoning by task complexity (see Model + Reasoning Selection). Default: gpt-5.6-terra at high.
3. Preflight before fan-out. Before launching multiple agents, confirm codex is authenticated and not rate-limited: run codex login status (or one cheap low-effort probe) first. Hitting a 401 or rate limit five agents into a fan-out wastes every agent already launched.
4. Spawn the subagent using the canonical invocation (Basic Usage). Pipe long prompts via stdin. For anything expected to run more than a minute — or any fan-out — run it in the background (see Background Fan-Out) so the parent keeps working.
5. Act autonomously while it runs. Don't ask for permission mid-flight; the parent only sees the final result, so mid-task pauses waste tokens. Pause only for genuinely destructive operations (data loss, external impact, security).
6. Monitor, don't fire-and-forget. Check completion, retry on failure, answer follow-ups if blocked. Feel free to run multiple sequential or parallel codex subagents.
7. Verify independently — mandatory. Codex reporting success is a claim, not a result (see Verification). Never relay its summary as verified fact, and never dispatch dependent work on top of an unverified result.
8. Present results, don't dump them. Summarize what Codex said in your own words, surface concrete code changes or recommendations, and leave the next move to the user. Subagent output is input for your synthesis. Keep your response to the user concise and specific.

Model + Reasoning Selection

Scale the model AND reasoning effort to task complexity. The GPT-5.6 family (gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna) is available and supersedes gpt-5.5; gpt-5.6-terra at high reasoning is the recommended default for delegated work (verified 2026-07).

Complexity	Model	Reasoning effort
Trivial (lookup, one-liner, format fix)	gpt-5.4-mini or gpt-5.3-codex-spark	low
Simple/short (small edit, quick search, basic script)	gpt-5.6-terra	low
Standard implementation (feature, refactor, multi-file)	gpt-5.6-terra	high
Hard/large/long-horizon (architecture, big migration, stuck bug, deep review)	gpt-5.6-terra (or gpt-5.6-sol)	xhigh

Set via -m <model> -c 'model_reasoning_effort="<effort>"'. gpt-5.5 remains valid as a fallback if a 5.6 variant errors. Check what's currently available: python3 -c "import json; [print(m['id']) for m in json.load(open('$HOME/.codex/models_cache.json'))['models']]".

Intelligent Prompting

Subagents only see what you give them. Be specific:

1. Context — what they're analyzing, where it lives.
2. Objectives — numbered, concrete.
3. Constraints — what to focus on, what to ignore.
4. Output format — exact shape the parent wants back.
5. Success criteria — when the task is done.

Template:

[TASK CONTEXT]
You are researching/analyzing/coding [TOPIC/EXPLANATION].

[OBJECTIVES]
1. ...
2. ...

[CONSTRAINTS]
- Focus on: ...
- Ignore: ...

[OUTPUT FORMAT]
Return: ...

[SUCCESS CRITERIA]
Complete when: ...

Good vs. Bad Prompts

Vague prompts produce vague work; specific prompts produce useful work.

Research

❌ "Research authentication"

✅ "Research authentication in this Next.js codebase. Focus on: 1) Session management strategy (JWT vs session cookies), 2) Auth provider integration (NextAuth, Clerk, etc), 3) Protected route patterns. Check /app, /lib/auth, and middleware files. Return architecture summary with code examples."

Web search / docs lookup

❌ "Search for Codex SDK"

✅ "Find the most recent Codex SDK documentation using the web and summarize key updates. Focus on: 1) Installation/quickstart, 2) Core API methods and parameters, 3) Breaking changes or deprecations. Prioritize official OpenAI docs and release notes. Return a concise summary with citations."

API discovery

❌ "Find API endpoints"

✅ "Find all REST API endpoints in this Express.js app. Look in /routes, /api, and /controllers directories. For each endpoint document: method (GET/POST/etc), path, auth requirements, request/response schemas. Return as markdown table."

Basic Usage

Default: pipe the prompt via stdin using - as the positional argument. Inline string prompts work for short ones, but anything with newlines, quotes, backticks, or $ should be piped to avoid shell-escaping bugs.

Canonical invocation (capture output to file, GPT-5.6-Terra with high reasoning):

cat <<'EOF' | codex exec --yolo --skip-git-repo-check \
  -m gpt-5.6-terra -c 'model_reasoning_effort="high"' \
  -o /tmp/codex-result.txt -
[TASK CONTEXT]
You are analyzing /path/to/repo.

[OBJECTIVES]
1. Do X
2. Do Y

[OUTPUT FORMAT]
Return: path - purpose
EOF

result=$(cat /tmp/codex-result.txt)

Variants (only what changes from the canonical form):

• Low-effort task (simple search, short fetch, basic lookup): swap -c 'model_reasoning_effort="high"' → -c 'model_reasoning_effort="low"'. Model stays gpt-5.6-terra.
• Hard/long-horizon task (architecture, big migration, stuck bug): raise to -c 'model_reasoning_effort="xhigh"'.
• Machine-parsable output: swap -o /tmp/codex-result.txt → --json, then pipe through jq -r 'select(.event=="turn.completed") | .content'. Prefer -o whenever possible — it skips JSON parsing and avoids terminal truncation on long outputs.

Parallel Subagents

Spawn multiple subagents for independent tasks — research two topics in parallel, or compare two approaches to the same problem. Each writes to its own -o file; wait for all, then read:

cat <<'EOF' | codex exec --yolo --skip-git-repo-check \
  -m gpt-5.6-terra -c 'model_reasoning_effort="high"' -o /tmp/agent-a.txt - &
Approach A: solve [problem] using [strategy A]. Return diff + rationale.
EOF

cat <<'EOF' | codex exec --yolo --skip-git-repo-check \
  -m gpt-5.6-terra -c 'model_reasoning_effort="high"' -o /tmp/agent-b.txt - &
Approach B: solve [problem] using [strategy B]. Return diff + rationale.
EOF

wait
RESULT_A=$(cat /tmp/agent-a.txt)
RESULT_B=$(cat /tmp/agent-b.txt)

The canonical compare-two-approaches pattern: give both subagents the same problem under different framings, wait, then synthesize the better answer in the parent.

Background Fan-Out (Claude Code parent)

When the parent is Claude Code, prefer its background-task machinery over shell &/wait for long runs and fan-outs: issue one Bash call per agent with run_in_background: true, each writing to its own -o file. The parent keeps working; the harness sends a task notification when each agent exits, and interim progress can be checked by Reading the task's output file.

• Give each agent a distinct, descriptive -o path (/tmp/codex-server.txt, /tmp/codex-ios.txt) — the filename is your only label when notifications arrive out of order.
• On each notification: read the -o file, verify the result (see Verification), then decide — dispatch the next slice, a fix agent, or nothing.
• Fan out only across genuinely independent work (different repos, packages, or modules). Don't launch agents whose inputs depend on another agent's unfinished output.
• Blocking &/wait is fine for short parallel pairs where the parent has nothing else to do.

Git Hygiene for Multiple Agents

Codex agents run --yolo and will happily commit over each other. Rules:

• One repo = one writer at a time. Parallel writers are safe only across different repos/packages — or give each agent its own git worktree.
• Tell each agent the tree state it will find: which branch to use, any uncommitted changes it must preserve, and explicitly whether it may commit/push or must leave changes uncommitted for the parent to review.
• If another agent or session may have committed meanwhile, instruct the agent to fetch and rebase before committing and to keep its change minimal.
• After any agent that commits, the parent checks git log/git status itself to confirm what actually landed and that nothing else was clobbered.

Verification (mandatory)

Codex's final message saying "done" is a claim, not a result. After every run, the parent independently verifies before reporting to the user or building on the result:

• Code changes: inspect git diff/git status, confirm the change is in the files it names.
• Builds/sites: rerun the build or check the built artifact for the specific expected change.
• Deploys/live content: fetch the live URL with a cache-buster (?v=$(date +%s)) and confirm the specific change is visible.
• Claims about code ("X is handled in Y"): spot-check the cited file/line.

If verification fails, dispatch a fix agent with the evidence — don't re-report the original claim.

Sequential Subagents

When the parent is driving a multi-step engagement — each next call is a judgment based on what just came back, not a mechanical retry. Spawn one subagent, read its output, decide what to do next (next slice of the work, a review pass, a redo, a different angle, a verification step), spawn the next one, repeat. The parent stays in the driver's seat the whole time:

# Step 1: dispatch the first subagent
cat <<'EOF' | codex exec --yolo --skip-git-repo-check \
  -m gpt-5.6-terra -c 'model_reasoning_effort="high"' \
  -o /tmp/codex-step-1.txt -
Implement the auth middleware in src/middleware/auth.ts per the spec at docs/auth.md.
Return: summary of changes + files touched.
EOF

# Step 2: parent reads /tmp/codex-step-1.txt, decides what's needed next.
# Could be: next part of the task, a critique pass, a redo, a verification — whatever fits.
# Always use a quoted heredoc (<<'EOF') for the template and `cat` the prior
# output on stdin — never interpolate $STEP_N into an unquoted heredoc.
# Codex output frequently contains backticks and $() sequences (code blocks,
# command examples), and bash would execute those during expansion.
{
  cat <<'EOF'
Review the auth middleware changes summarized below for security holes
(token leakage, timing attacks, missing CSRF). Return: issues + line refs.

[PRIOR WORK]
EOF
  cat /tmp/codex-step-1.txt
} | codex exec --yolo --skip-git-repo-check \
  -m gpt-5.6-terra -c 'model_reasoning_effort="high"' \
  -o /tmp/codex-step-2.txt -

# Step 3: parent reads /tmp/codex-step-2.txt, dispatches a fix pass — or moves
# on to the next slice of work entirely. Keep going until the parent decides done.

The shape: call → read → decide → call → read → decide. Each prompt is composed fresh in the parent based on what just landed. There's no fixed loop count and no shared template — every step can be a totally different task (implement, review, refactor, sanity-check, redo from scratch). Feed prior outputs into later prompts whenever the next subagent needs that context to do its job.

Resuming a session (follow-ups)

Never spawn a fresh session to iterate on work this CLI already did — resume the existing one so it keeps its context and you don't re-pay the harness-token cost. Verified working headless (2026-07):

codex exec resume --last -m <model> -c 'model_reasoning_effort="<effort>"' "<follow-up>"
# or by id: codex exec resume <SESSION_ID> ...   (id from the first run's session file / --json output)

Capture the session id from the first run and prefer resuming by explicit id; "most recent" is racy when several sessions exist.

Quota failover

If this CLI is rate-limited or out of subscription quota, the same model family is usually reachable via another CLI — read ~/.claude/skills/cli-model-overlap.md for the failover map (cursor is the hub carrying all families).