Codex CLI as a Subagent

When to Use

• Use when a bounded coding, review, or verification task can run in a separate Codex CLI session.
• Use when parallel work needs explicit file ownership and a clear definition of done.

Codex CLI is OpenAI's terminal coding agent. codex exec runs it non-interactively: it works autonomously in a sandbox, streams progress to stderr, and prints only the final message to stdout. Auth reuses the user's ChatGPT subscription — never an API key.

When to delegate

• Self-contained coding task with clear success criteria (fix, feature, refactor, review).
• Parallel work: several independent tasks at once (see Parallel runs).
• Second opinion / independent verification of your own changes.

Do NOT delegate tasks that need conversation context you can't fully write into the prompt.

Preflight

codex --version       # missing? npm i -g @openai/codex  (or: brew install --cask codex)
codex login status    # exit 0 + "Logged in using ChatGPT" = ready

Not logged in → stop and tell the user to run codex login (one-time browser OAuth). Never read, print, or copy credentials (~/.codex/auth.json).

Launch

OUT=$(mktemp /tmp/codex-out.XXXXXX)
codex exec \
  --cd /path/to/repo \
  --sandbox workspace-write \
  --output-last-message "$OUT" \
  "Full task prompt: goal, constraints, files to touch, definition of done." \
  </dev/null

• </dev/null is MANDATORY when stdin is not a real terminal (background shells, scripts): codex treats open stdin as extra context and waits forever for EOF.
• Codex sees NOTHING of your conversation. Put all context in the prompt: goal, relevant paths, constraints, and how to verify it's done.
• Long prompt? Pipe it via stdin instead: codex exec [flags] - < /tmp/task.md.
• Wrap the command in a background/Bash subagent if your host agent has one (Cursor: Task tool with a shell subagent) so Codex's verbose stream stays out of the parent context. Fallback: a plain background terminal.
• Runs take minutes and have no built-in timeout — background it and monitor.