Codex Subagent

Codex CLI as a Subagent

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." \
  ` to override the model, `--json` for JSONL event stream.

## Collect results

```bash
cat "$OUT"                            # final message = the deliverable
git -C /path/to/repo status --short   # see what Codex actually changed

Follow-up in the same session (run from the same cwd — resume filters by cwd):

codex exec resume --last "follow-up instruction" </dev/null

Parallel runs

Parallelize only genuinely independent tasks, and assign file ownership upfront so results merge cleanly. One git worktree per Codex run — never two in the same tree:

git worktree add /tmp/wt-taskA -b codex/task-a
codex exec --cd /tmp/wt-taskA --sandbox workspace-write -o /tmp/outA.md "task A" </dev/null

Failure modes

• Hangs forever with no output → stdin was left open. Kill it, relaunch with </dev/null.
• codex login status non-zero → the user must run codex login. Don't work around it.
• ChatGPT plan rate limit hit → report to the user; never retry in a loop.
• "Not a git repo" error → add --skip-git-repo-check, or init a repo first.
• Network is blocked inside the workspace-write sandbox by default. If the task

needs it (installs, API calls): -c sandbox_workspace_write.network_access=true.

• NEVER use --dangerously-bypass-approvals-and-sandbox.

Rules

• One task per launch. Split big jobs into multiple launches.
• Review Codex's diff yourself before declaring the task done.

Cursor-native wrapper (optional)

For auto-routing and /codex invocation inside Cursor, add ~/.cursor/agents/codex.md — a custom subagent whose description is "delegates coding tasks to Codex CLI" and whose body points at this skill.

Source & license

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

• Author: davidondrej
• Source: davidondrej/skills
• License: MIT

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