delegate-to-codex

Delegate to Codex (CLI)

Run codex exec non-interactively for a second opinion, review, or a delegated edit worker. Model default: gpt-5.6-sol at -c model_reasoning_effort='"high"' (medium/low only for small or mechanical work).

Happy path

1. Isolate. Read-only work runs in the current checkout with -s read-only:

   slug="codex-$(date +%Y%m%d-%H%M%S)"
   run_dir="/tmp/codex-$slug"; mkdir -p "$run_dir"
   

   Edit work gets its own worktree instead, so the diff is easy to inspect or discard:

   slug="codex-$(date +%Y%m%d-%H%M%S)"
   worktree="../$(basename "$PWD")-$slug"
   git worktree add -b "agent/codex/$slug" "$worktree" HEAD
   run_dir="$worktree/.agent-runs/$slug"; mkdir -p "$run_dir"
   

2. Write the brief to $run_dir/prompt.md. Include context, exact task, constraints, verification commands, output contract — and a hard completion criterion: GPT-5.6 Sol is exploratory and keeps widening scope without an unambiguous definition of "done".

3. Launch. Always feed the prompt from the file with - < prompt.md; never pass it as a bare argument under a harness (see Gotchas: stdin wedge).

   Read-only reviewer / second opinion:

   codex exec -C "$PWD" \
     -m gpt-5.6-sol -c model_reasoning_effort='"high"' \
     -s read-only --json -o "$run_dir/final.md" \
     - < "$run_dir/prompt.md" > "$run_dir/events.jsonl"
   

   Edit worker — same command with -C "$worktree" and --sandbox workspace-write instead of -s read-only.

   Research briefs that need current information: add -c tools.web_search=true.

4. Harvest. Final answer in $run_dir/final.md; session id in the thread.started event in $run_dir/events.jsonl. For edit work also: diff via git -C "$worktree" diff — harvest from the working tree, not branch history, since the worker's commits may be missing (see Gotchas) — and run a fresh read-only reviewer over the diff before merging.

Gotchas

• A missing codex binary or stale auth surfaces mid-run as an abort — or a hang indistinguishable from the stdin wedge. Preflight codex --version and auth (codex login, ChatGPT auth, or a scoped CODEX_API_KEY/OPENAI_API_KEY) before long runs.
• Stdin wedge. codex exec reads piped stdin whenever you pass -, no prompt, or a prompt argument — and under a harness stdin never closes, so it wedges at startup (0% CPU, no output). Use - < prompt.md, or add < /dev/null to any argument form. Never codex exec "$(cat prompt.md)" bare.
• Workers cannot commit in a linked worktree. The sandbox can't write the parent repo's .git/worktrees/<name>, so git commit/git merge fail even with workspace-write. The orchestrator runs all git commands; workers only edit and resolve content. Commit-shaped deliverable: brief the worker "commit; if commit fails, produce a git bundle" and fetch from the bundle.
• codex exec review --base <ref> recurses on 0.144.1 — re-execs itself endlessly, emits no findings, leaves stray processes. Review with plain codex exec -s read-only and a "review the diff between and HEAD" prompt instead.
• codex exec resume rejects the exec flags (-C -m -c -s --json -o, exit 2), so resumed turns run on config defaults. Prefer a fresh self-contained run that embeds the prior finding; if you must resume: codex exec resume --last "..." < /dev/null.
• A crashing MCP server in ~/.codex/config.toml aborts the whole run. Pass --ignore-user-config (auth still resolves via CODEX_HOME) and re-specify -m/-c on the CLI.
• ChatGPT-plan usage limits abort runs mid-flight with a reset time. Fall back to another vendor until then.
• -s read-only is a hard filesystem boundary — commands that write caches or build artifacts fail under it.
• -p selects a config profile, not an agent persona; custom subagents are TOML files under .codex/agents/ or ~/.codex/agents/.
• codex apply applies the latest agent diff to the current tree — check pwd and branch first.
• Worktrees omit ignored files. Copy only explicit prerequisites (e.g. .env.local), never secret directories. If the worker needs uncommitted local changes, apply an explicit patch in the worktree — never checkpoint unrelated user WIP with git add -A.

Not possible

• No approval prompts in exec mode: -a/--ask-for-approval is rejected.
• No --search flag on codex exec — use -c tools.web_search=true.
• No worktree creation or cleanup — manage them yourself.
• No resuming --ephemeral runs.
• The sandbox is not security isolation: --dangerously-bypass-approvals-and-sandbox only inside a bounded container/VM/CI runner — a worktree is not a security sandbox.

Evidence and full mechanics behind each gotcha: reference/gotchas.md.