---
name: codex-subagent
description: "Launch Codex CLI as an isolated subagent for bounded coding, review, or verification tasks."
category: agent-orchestration
risk: critical
source: community
source_repo: davidondrej/skills
source_type: community
date_added: "2026-07-07"
author: davidondrej
tags: [codex, subagents, delegation]
tools: [claude, codex]
license: "MIT"
license_source: "https://github.com/davidondrej/skills/blob/main/LICENSE"
disable-model-invocation: true
---

# 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. Confirm the user's intended authentication mode and account; this workflow assumes ChatGPT login and must not silently switch to billable API-key authentication.

## 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 \
  --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.
- Optional: `-m <model>` 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):

```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 --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

- Delegate only when the user or applicable project instructions authorize it. Installing this skill alone does not authorize new agents, external disclosure, or extra spending.
- 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.

## Limitations

- Adapted from `davidondrej/skills`; verify local paths, tools, credentials, and agent features before acting.
- For commands, remote access, scheduling, browser automation, or file-changing workflows, get explicit user approval and confirm the target environment first.


---
Source attribution: davidondrej/skills contributors, via Agentic Awesome Skills
Original project: https://github.com/davidondrej/skills
License: MIT + CC-BY-4.0
License information: https://creativecommons.org/licenses/by/4.0/
Original upstream instructions; downloaded from Mega AI Hub.

## Upstream license notice

MIT License

Copyright (c) 2026 David Ondrej

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.



# Mega AI Hub resource metadata

Creator / publisher: davidondrej/skills contributors, via Agentic Awesome Skills
Original project: https://github.com/davidondrej/skills
Attribution basis: Recorded upstream repository

Fields of work: Development & Engineering
Roles: Software Developer
Specialties: Specialty not specified
Tools: Tool not specified
Country applicability: Country not specified
Classification basis: Dave AI task classification from package title, description, and declared metadata
Instruction SHA-256: e7bfeebeb672d1abcf1ad61b875569720598ff8b608376b9ec22e63c5d9bf646
Metadata reviewed: 2026-10-27
This metadata supersedes earlier Mega AI Hub catalog attribution. Original instruction and supporting files are preserved.