Codex Subagent

Codex as Worker Subagent

Claude is the orchestrator. Codex is a worker subagent with its own fresh context window, its own network access, and its own sandboxed shell. You hand Codex a well-scoped task and take back a short answer. Codex's thinking, tool calls, and file reads happen in Codex's context, not yours — that is where the token savings come from.

Thin-forwarder contract

Treat each Codex call like a function call:

• You write the prompt (the "arguments")
• Codex runs its own full agent loop inside its own context
• You take Codex's stdout as the authoritative return value
• No Claude-side freelancing — don't "edit" what Codex said in your head

and then act on a phantom version. If Codex's answer is wrong or under- specified, resume the session with a follow-up or dispatch a fresh call with a better prompt. Do not pretend you know what it meant.

When to delegate

Delegate when any of these apply:

• Network needed. Web search, fetching docs, scraping an API,

checking a package version, gh api, npm view, pip install. You (Claude) pay steep token cost for WebFetch/WebSearch; Codex's network calls happen in its own context.

• Large reads. Scanning a repo, digesting a long file/log, cross-

referencing many sources.

• Long output that just needs a conclusion. E.g. "find all TODOs and

tell me which are stale" — Codex emits the list internally and returns only the verdict.

• Writing long files. Codex writes in its sandbox; you only see

"wrote foo.py (240 lines)".

• Running tools you'd rather not stream. Tests, builds, linters,

data-processing scripts.

• You're stuck. If your own attempt has stalled or you want a fresh

second pass with no prior context, dispatch Codex with a clean problem statement. That's explicitly the best-case use from the codex-plugin-cc design — "rescue" mode.

When NOT to delegate

• Quick decisions you can make from existing context.
• Tasks that depend tightly on conversation state that would be painful

to re-explain.

• One-line edits you could Edit directly with less overhead than

composing a Codex prompt.

• The user is clearly expecting you to do it interactively ("let's walk

through this together").

Gut check: if the task would cost you more than ~3k tokens of reads/ searches, delegate. If it's under ~1k, just do it.

Command shape

Canonical invocation for Codex CLI 0.141.0+:

filename=$(openssl rand -hex 4)
codex exec --skip-git-repo-check --sandbox  \
  [-C ] [--add-dir ] [-p ] \
  [--config web_search="live"] [--json] [-o ] [--output-schema ] \
  [--ephemeral] [--config model_reasoning_effort=""] \
  "" \
  2>>"/tmp/codex-${filename}.log"

Flag meanings:

• exec — non-interactive. No TUI, no mid-run approval prompts.
• --skip-git-repo-check — always pass this. We don't want Codex

refusing to run just because the cwd isn't a git repo.

• --sandbox — use read-only, workspace-write, or

danger-full-access. See the adaptive ladder below.

• --full-auto — deprecated compatibility alias. Do not use it in new

prompts or scripts. Prefer explicit --sandbox workspace-write.

• -C — run Codex with a specific working directory. Pass this

whenever the task is scoped to a specific project folder; saves Codex a cd round-trip.

• --add-dir — add a second writable/readable root when a task

genuinely spans another local directory. Explain why in the status line.

• -p — if the user has profiles defined in ~/.codex/config.toml

(reviewer, debugger, security, etc.), reference them by profile name and let the profile carry model/sandbox/approval preferences.

• --config web_search="live" — enable live web search for codex exec.

The interactive top-level codex command also has --search, but current codex exec expects the config override. The helper script accepts --search and maps it to this config value.

• --json — stream Codex events as JSONL for automation. Only use when the

caller asked for machine-readable event logs or a wrapper will parse them.

• -o / --output-last-message — save the final answer to a

file while still printing stdout. Good for handoffs, CI summaries, and downstream scripts.

• --output-schema — require the final response to match a JSON

Schema when another program will consume the result.

• --ephemeral — avoid persisting session files. Use for throwaway checks,

secrets-adjacent diagnostics, and CI jobs that do not need resume.

• --ignore-user-config / --ignore-rules — use only for controlled

automation where user config or execpolicy rules would make results non-reproducible. Mention the tradeoff.

• --config model_reasoning_effort="" — raise for

audits, security reviews, and tricky debugging; leave unset for normal work. Don't override the user's default model unless they asked.

• Prompt as the last positional argument, quoted. For long/multi-

line prompts, use heredoc on stdin:

``bash filename=$(openssl rand -hex 4) codex exec --skip-git-repo-check --sandbox workspace-write \ 2>>"/tmp/codex-${filename}.log" /dev/null

2>/dev/null throws away stderr, so when a call fails you have nothing to diagnose. The alternative here — steal from codex-cli-setup — is:

1. Generate a random per-call filename.
2. Redirect stderr to /tmp/codex-.log instead of /dev/null.
3. On success, ignore the log (temp file, OS cleans it up later).
4. On failure (non-zero exit or suspicious output), read the log to

see Codex's thinking stream and real error messages.

You get clean stdout for happy path and full debugging info on failure, without ever bloating Claude's context on the happy path.

Sandbox ladder (adaptive, no-prompt)

This skill uses non-interactive codex exec. Pick the right execution mode up front and run the worker to completion. If the user wants step-by-step accept/deny, use Codex interactive/TUI instead of this dispatch wrapper.

The user has authorized adaptive escalation: default to --sandbox workspace-write, escalate to bypass/full access whenever the task actually needs it, without stopping to ask. Don't over-escalate — use the minimum that gets the job done and explain the choice in one line.

Precedence is strict:

1. Explicit CLI/helper flags win.
2. Persona frontmatter supplies defaults only when the caller did not specify

--sandbox or --effort.

1. Wrapper defaults apply last.

This means a network-heavy persona such as researcher may default to bypass, but --sandbox workspace-write must remain workspace-write when the caller sets it explicitly. Likewise, explicit --effort default means do not emit a model_reasoning_effort override.

| Task shape | Sandbox | Flag | | --- | --- | --- | | Read-only analysis inside workspace | workspace-write is fine | --sandbox workspace-write | | Local edits / file writes inside a project | workspace-write | --sandbox workspace-write | | Current public facts through Codex web search only | workspace-write + live search | --sandbox workspace-write --config web_search="live" | | Anything needing shell network (curl, pip install, npm view, gh api, package installs, remote API calls) | bypass/full access | --dangerously-bypass-approvals-and-sandbox | | Operating outside the workspace (system paths, ~/.config, other drives) | bypass | --dangerously-bypass-approvals-and-sandbox | | Installing global tools, modifying global state | bypass | --dangerously-bypass-approvals-and-sandbox |

Do tell the user in your one-line status update which sandbox you picked and why — so they can correct you if your read was wrong. No approval needed, but transparency yes.

Truly destructive ops (rm -rf outside workspace, dropping a database, force-push, rewriting git history) → stop and confirm with the user first regardless of sandbox mode. The sandbox protects the filesystem; it does not divine the user's intent.

Windows note: if read-only or workspace-write fails before commands run with a Windows sandbox ACL error such as apply deny-read ACLs, classify the result as partial, report the exact error, and retry with --dangerously-bypass-approvals-and-sandbox only when the task is non- destructive and the user/workflow already authorizes full local access.

Output and automation options

Use Codex's extra flags deliberately:

| Need | Flag | Guidance | | --- | --- | --- | | Human-readable answer | default stdout | Best default; keep prompts terse. | | Save final answer | -o | Use for repo-local handoff, CI summaries, or artifacts. | | Parse every event | --json | JSONL event stream; wrappers parse it, humans usually don't need it. | | Stable machine output | --output-schema | Use when downstream code needs fields, not prose. | | Fresh current web facts | --config web_search="live" | For Codex exec web search; the helper's --search option maps to this. | | Throwaway run | --ephemeral | No persisted session, so do not expect resume. | | Extra root | --add-dir | Prefer one scoped extra directory; avoid broad drive roots. |

Reasoning effort by task class

Default to codex's configured defaults. Override with --config model_reasoning_effort="" only when the task class warrants it:

| Task class | Effort | Why | | --- | --- | --- | | Quick lookup, version check, single-file read | (default) | Not worth the extra tokens | | Normal code edits and refactors | (default) | Codex's default is tuned for this | | Audit, security review, "find all bugs" | high | Needs exhaustive exploration | | Debugging a subtle failure | high | Needs careful reasoning | | Bulk scan / pattern matching over many files | medium | Balance speed and coverage |

Don't ask the user which model or effort to use — pick a sensible default and mention it in the status line. If they want different, they'll say so.

Writing prompts for Codex

Codex is a capable coding agent, not a dumb shell. Treat it like a competent colleague who just walked into the room — no memory of your conversation, no context on why the task matters.

A good Codex prompt has:

1. The goal. What "done" looks like.
2. Scope hints. Which directory, which files, which language.
3. Return format. What you want back. "Reply with just the version

number.", "Return a JSON array of {file, line, issue}.", "Summary under 200 words." Codex is very willing to be terse if asked — and terseness is token savings.

1. Guardrails, when non-obvious. "Don't modify tests.", "Don't touch

anything outside src/api/."

For complex dispatches, use a compact block contract:

Do . Done means .

Workspace: 
Inspect: 
Out of scope: 

Edits: allowed|not allowed
Network: none|web-search-only|shell-network-ok
Destructive actions: stop and ask before executing

Use current files, command output, tests, and official docs. Do not guess.
Separate verified facts, evidence-based inference, and unknowns.

Run relevant checks after edits. If a check fails, diagnose and make the
smallest scoped fix unless blocked by missing credentials, external state, or a
safety gate.

Return the requested format plus validation outcomes and unverified items.

The full public guide for prompt, agent, skill, command, result-handling, and publication patterns lives in the source repository at docs/prompt-and-agent-patterns.md.

Example — bad:

"check what version of react we're on"

Example — good:

"Read package.json in the current directory and report just the 'react'
 version string. No other output."

Example — web-search delegation:

filename=$(openssl rand -hex 4)
codex exec --skip-git-repo-check \
  --dangerously-bypass-approvals-and-sandbox \
  2>>"/tmp/codex-${filename}.log"  released 
EOF

Example — bulk analysis with structured return:

filename=$(openssl rand -hex 4)
codex exec --skip-git-repo-check --sandbox workspace-write -C /path/to/repo \
  --config model_reasoning_effort="high" \
  2>>"/tmp/codex-${filename}.log" 1 year old
based on git blame). Return a markdown table:
  | file:line | comment | stale? | reason |
No prose. Just the table.
EOF

Resume-first pattern

Before launching a new call, consider: is there a recent Codex session still relevant to what you're about to ask? Codex keeps session state. Resume is cheap; a new session discards everything Codex already learned.

Resume syntax (prompt via stdin):

filename=$(openssl rand -hex 4)
echo "Your follow-up prompt" | codex exec --skip-git-repo-check \
  resume --last - 2>>"/tmp/codex-${filename}.log"

Or with heredoc:

filename=$(openssl rand -hex 4)
codex exec --skip-git-repo-check resume --last \
  - 2>>"/tmp/codex-${filename}.log" 30s, big analyses, audits, large writes) should go
into the background rather than blocking your turn:

1. Dispatch with Bash `run_in_background: true`. You get a task_id
   immediately and can continue other work.
2. Do other useful work while it runs — read a related file, plan the
   next step, write a helper.
3. When you need the result, call `TaskOutput` on the task_id with
   `block: true`. You'll either get the finished output or wait for it.
4. If the user wants to cancel, use `TaskStop`.

This is the closest equivalent to `codex-plugin-cc`'s
`/codex:status` + `/codex:result` + `/codex:cancel` lifecycle, using
primitives you already have.

## Handling the outcome

Codex's stdout is your return value. Before you act on it, classify it:

- **`success`** — call exited 0, stdout answers the prompt, nothing
  looks off. Proceed. Ignore the stderr log.
- **`partial`** — call exited 0 but stdout is empty, truncated, asks
  clarifying questions back at you, or hits a known failure mode
  (refused to run, couldn't find file, hit a permission wall). Check
  the stderr log for why, then either: (a) fix the prompt and dispatch
  fresh, (b) escalate the sandbox and retry, or (c) resume with a
  clarification.
- **`error`** — non-zero exit. **Don't silently retry.** Read the
  stderr log first and diagnose. Common failures and fixes:

  | Symptom | Likely cause | Fix |
  |---|---|---|
  | `refusing to run outside a git repository` | Missing `--skip-git-repo-check` | Add the flag |
  | `operation not permitted` / sandbox denial | Need higher sandbox | Escalate `--sandbox workspace-write` -> bypass |
  | `network unreachable` / DNS failure | Shell network under workspace sandbox | Use `--config web_search="live"` for web-search-only tasks or `--dangerously-bypass-approvals-and-sandbox` for shell network |
  | `apply deny-read ACLs` on Windows | Codex Windows sandbox failed before command execution | Report the exact error; retry with bypass only for authorized non-destructive work |
  | `127` command not found | `codex` not on PATH | Surface to user, don't retry |
  | Codex asked a clarifying question in output | Under-specified prompt | Rewrite prompt with clearer goal / return format |
  | Empty output / hit timeout | Task too big for one call | Split into subtasks, or raise timeout |

## Using Codex's answer

Once you have a `success` result:

1. **Read carefully.** Don't parrot stdout back to the user verbatim —
   extract what they actually need and summarize.
2. **Verify when it matters.** Codex runs on OpenAI models with their own
   cutoffs and can be wrong — especially about recent library versions,
   model names, APIs, or post-cutoff changes. If the answer is load-
   bearing and you have reason to doubt, cross-check (your own
   knowledge, a second Codex call with a different phrasing, or a
   direct tool).
3. **Disagree explicitly and resume.** If Codex is wrong, don't just
   quietly ignore it. Resume the session and push back with evidence.
   Frame it as peer discussion, not correction — either AI could be
   wrong:

   ```bash
   filename=$(openssl rand -hex 4)
   echo "This is Claude

…

## Source & license

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

- **Author:** [dwgx](https://github.com/dwgx)
- **Source:** [dwgx/claude-codex-subagent](https://github.com/dwgx/claude-codex-subagent)
- **License:** MIT

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