Skip to content
Skills Library
AI & agents · Automation

codex-subagent

/codex-subagent

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.

Repository
skills ↗
Licence
MIT
Last repository change
26.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

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.

Original author description

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.

How it works

  1. When to delegate
  2. Preflight
  3. Launch
  4. Collect results
  5. Parallel runs
  6. Failure modes
  7. Rules
  8. Cursor-native wrapper (optional)
Original SKILL.md headings · 99 lines, 585 words
SKILL.md preview
---
name: codex-subagent
description: 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.
disable-model-invocation: true
triggers: [user, model]
---

# 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.
Files in this package (2)
  • SKILL.md 4 KB
  • agents/openai.yaml 1 KB

Versions

RepositoryScoreLicence
This page · davidondrej/skills100MIT
RemakeBench/skills100MIT

Database snapshot: 13.11.2026 · package version 3a9822c6dbfd (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100codex
    Run OpenAI Codex CLI as a subagent for second opinions, code reviews, and questions. Use when you want a different AI model's perspective.
  • 100codex
    Invoke the OpenAI Codex CLI for cross-model collaboration, a second opinion, or delegated work. Use when the user asks Codex to review, debug, explain, plan or implement something, or names a Codex model.
  • 100delegating-to-codex
    Delegates a task to OpenAI Codex running as an interactive session in a herdr pane - uses the user's ChatGPT subscription, visible in herdr, steerable mid-session. Use when delegating work to codex, offloading a task to a GPT model (sol, terra, luna), or running a second opinion…
  • 100codex
    Use the local Codex CLI as an independent second agent. Two branches — (1) proactively run `codex review` for a second opinion after completing a substantive change, before presenting it as done or committing; (2) delegate a well-defined implementation task via `codex exec`,…
  • 100second-opinion
    Get a second opinion from another AI model (currently OpenAI models, via the codex CLI) on a design decision, a stubborn bug, a code review, or any question where an independent take is valuable. Use only when the user explicitly asks for one -- "get a second opinion", "ask…
  • 100local-codex
    Launches and manages the local OpenAI Codex CLI as a non-interactive coding sub-agent via ChatGPT OAuth, never API keys. Use to delegate coding tasks to Codex, run codex exec, generate or refactor code, or get a Codex code review; phrases like 'codex', 'run codex', 'codex exec', 'delegate to codex'.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.