Claude Code vs Codex: The Split I Use to Ship Production Code

---
description: Consult a persistent Codex (GPT-5) subagent via the CLI, dispatched through Monitor so the turn runs non-blocking and notifies you on completion; captures a re-invokable thread handle for follow-ups on the SAME conversation.
argument-hint: "<what to ask/task Codex> [--resume [id]] [--repo PATH]"
disable-model-invocation: true
---

You are wielding Codex as a subagent — the Codex (via CLI) equivalent of your native Agent Tool. Codex is a GPT-5 agent running a real, persistent conversation: you spawn it once and re-invoke it by handle. Treat it as a capable peer architect engineer — consult it, delegate investigation, get a second opinion.

**Same repo context as you — do NOT over-feed it.** Codex runs with `-C <repo>` and reads the full tree: it can inspect files, run `git` (log/diff/blame/show), grep the tree, and hit the network. So do NOT paste code snippets, diffs, file dumps, or long transcripts it can fetch itself; point it at paths / symbols / commands / a branch or SHA and let it look. Quote a snippet ONLY when that exact line IS the point of discussion — never as a substitute for access it already holds. It's a peer agent working the same codebase, not a blind chatbot.

**Permissions: read-only by default; full access is user-run.** The templates below run `-s read-only` — Claude Code's auto-mode permission classifier blocks `--dangerously-bypass-approvals-and-sandbox` (see `docs/sops/codex-agent-tool.md`), and read-only fully covers consults/reviews, the dominant use. When Codex must WRITE, don't silently downgrade the task: say so and have the user run the command themselves with `--dangerously-bypass-approvals-and-sandbox` in place of `-s read-only` (unrestricted internet + any file, zero approval prompts — how Alber runs Codex).

**Reasoning: ALWAYS high.** Pin `-c model_reasoning_effort="high"` on every call; never let it inherit a lower interactive default.

## One path: dispatch through Monitor

Every job goes through the SAME mechanism.

1. Write the ask to `$SP/prompt.txt` (sidesteps all shell quoting).
2. Fire a **Monitor** whose command IS the `codex` run: events → file, and a single line on exit carrying `rc` + the thread handle.
3. Keep working. Codex *exiting* is the terminal signal — Monitor notifies you in chat (`rc=0` success, `rc≠0` failure, timeout = killed). Do NOT poll or sleep.
4. On the event: **Read** `$SP/last-answer.txt` (the clean answer). The handle is in `$SP/last-thread`.

State lives in your **session scratchpad**.

### Your Agent Tool ⇄ Codex

```yaml
# native operation        →  Codex equivalent (always fired via Monitor)
- native: spawn subagent
  codex: codex exec --json                     # handle = thread.started.thread_id
- native: SendMessage(to id, prompt)
  codex: codex exec resume <id>                # follow-up, full continuity
- native: new / independent subagent
  codex: fresh codex exec                      # new thread_id
```

## Spawn (t=0)

**Step A — Bash**, write the ask:

```bash
SP="<your session scratchpad>/codex-agent-tool"; mkdir -p "$SP"   # ephemeral (fallback: $TMPDIR)
cat > "$SP/prompt.txt" <<'EOF'
<the ask — flags stripped>
EOF
```

**Step B — Monitor** (`description: "codex: <short label>"`, `timeout_ms: 1800000`, `persistent: false`), command:

```bash
SP="<your session scratchpad>/codex-agent-tool"
codex exec --json -s read-only --skip-git-repo-check \
  -c model_reasoning_effort="high" -C "${REPO:-$PWD}" \
  -o "$SP/last-answer.txt" "$(cat "$SP/prompt.txt")" </dev/null \
  >"$SP/last-events.jsonl" 2>"$SP/last-err.log"
rc=$?
grep -o '"thread_id":"[^"]*"' "$SP/last-events.jsonl" | head -1 | sed 's/.*:"//;s/"$//' > "$SP/last-thread"
echo "codex done rc=$rc thread=$(cat "$SP/last-thread")"
```

On the completion event: `rc=0` → **Read** `$SP/last-answer.txt`. `rc≠0` → **Read** `$SP/last-err.log` and report the failure.

## Follow-up (t=2) — re-invoke the same agent

Same path, same Monitor; only `exec` → `exec resume "$TID"`.

**Step A — Bash**, write the follow-up:

```bash
SP="<your session scratchpad>/codex-agent-tool"
cat > "$SP/prompt.txt" <<'EOF'
<your follow-up>
EOF
```

**Step B — Monitor** (same params), command:

```bash
SP="<your session scratchpad>/codex-agent-tool"
TID=$(cat "$SP/last-thread")            # or a specific id you tracked
codex exec -C "${REPO:-$PWD}" resume "$TID" --json --skip-git-repo-check \
  -c model_reasoning_effort="high" \
  -o "$SP/last-answer.txt" "$(cat "$SP/prompt.txt")" </dev/null \
  >"$SP/last-events.jsonl" 2>"$SP/last-err.log"
echo "codex done rc=$? thread=$TID"
```

## Params (optional)

- `--repo PATH` → substitute `REPO=PATH` so Codex inspects that codebase (`-C`). Default: cwd.
- `-m <model>` → override Codex's model. Leave default unless the user names one explicitly.
- Job expected to exceed 30 min? Raise `timeout_ms` (Monitor max `3600000` = 60 min).

## Gotchas (do NOT trip)

- The prompt goes through `$SP/prompt.txt`, never inlined — arbitrary text breaks shell quoting.
- `</dev/null` is mandatory or `exec` hangs reading stdin.
- `resume` re-stamps the thread's cwd with wherever it runs — pass `-C` consistently for repo-bound threads, but place it on the `exec` parent **before** the `resume` subcommand (`codex exec -C <dir> resume <id> …`). `codex exec resume` rejects `-C`/`-s`/`-a` as its own flags (`error: unexpected argument '-C' found`). It inherits the session's sandbox (do NOT pass `-s/-a`) but DOES accept `--dangerously-bypass…`, `-c`, `--json`, `-o`.
- Running several parallel Codex threads? Track each id yourself; `$SP/last-thread` only holds the most recent.
- Full findings & dragons: `~/Repos/codex-agent-tool/docs/` (machine-local on Alber's setup — not in this repo; the load-bearing gotchas are inlined above and in `docs/sops/codex-agent-tool.md`).

## Report back

A thread's Desktop-UI visibility is decided by its **origin source**, which `resume` never changes (verified: after CLI resumes, a seeded thread keeps `source=vscode` in both `state_5.sqlite` and the catalog):

- **Fresh `codex exec` spawn → invisible in Desktop.** It's stamped `session_source=Exec`, which the Desktop's `thread/list` filters out (only interactive sources surface: `cli`/`vscode`/`atlas`/`chatgpt`). Confirmed in source (`rollout` `INTERACTIVE_SESSION_SOURCES` + app-server `filters.rs`) and against the derived catalog the sidebar actually reads (`~/.codex/sqlite/codex-dev.db` → `local_thread_catalog`, `source_kind`). Editing `source` in raw `state_5.sqlite` does **not** fix it. So for a spawn you started, the user has **no** Desktop view — **relay what matters**. Inspect it yourself via `codex resume <id>` (CLI).

- **Seed trick (Alber's habitual mode) → visible in Desktop.** If the user seeds the conversation *in the Desktop first* (an interactive `vscode` thread) and hands you its id, drive it with `codex exec resume <id>`: the append preserves the interactive source, so the user sees the whole exchange — your follow-ups + Codex's answers — **in that Desktop thread after a full quit + reopen of Codex.app** (cold-start rehydrates from the rollout; the live app does NOT hot-reload CLI-appended turns). When the user passes you an id (`--resume <id>`), assume they intend to read it in the Desktop — write for that audience too.

Dragons: `~/Repos/codex-agent-tool/docs/external/quirks/` (Alber's machine — not in this repo).