# 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.

- **Type:** Skill
- **Install:** `agentstack add skill-davidondrej-skills-codex-subagent`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [davidondrej](https://agentstack.voostack.com/s/davidondrej)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [davidondrej](https://github.com/davidondrej)
- **Source:** https://github.com/davidondrej/skills/tree/main/skills/agent-orchestration/codex-subagent

## Install

```sh
agentstack add skill-davidondrej-skills-codex-subagent
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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 \
  --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):

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

- 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](https://github.com/davidondrej)
- **Source:** [davidondrej/skills](https://github.com/davidondrej/skills)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-davidondrej-skills-codex-subagent
- Seller: https://agentstack.voostack.com/s/davidondrej
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.