codex-subagent

Original：🇺🇸 English

Translated

Launch OpenAI Codex CLI as a subagent (ChatGPT subscription auth, no API key). Use when delegating a self-contained coding task to Codex from another agent — parallel implementation work, a second opinion, or an independent verification pass.

18installs

Sourcedavidondrej/skills

Added on2026-09-06

NPX Install

npx skill4agent add davidondrej/skills codex-subagent

SKILL.md Content

View Translation Comparison →

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

bash

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

bash

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

Always use GPT 5.6 Sol (
```
gpt-5.6-sol
```
). Default reasoning effort to
```
high
```
. Pass both flags explicitly on every new Codex run.
Do NOT use Codex fast mode.
```
</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.
Optional:
```
--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):

bash

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:

bash

git worktree add /tmp/wt-taskA -b codex/task-a
codex exec --cd /tmp/wt-taskA --model gpt-5.6-sol \
  --config model_reasoning_effort=high --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.

codex-subagent

NPX Install

Tags

SKILL.md Content

Codex CLI as a Subagent

When to delegate

Preflight

Launch

Collect results

Parallel runs

Failure modes

Rules

Cursor-native wrapper (optional)