codex-subagent
Launch OpenAI Codex CLI as a subagent (ChatGPT subscription auth, no API key)
Install / Use
npx skills add davidondrej/skills --skill codex-subagentInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
AI & Machine LearningSupported Platforms
Our assessment of codex-subagent
codex-subagent scores 88/100 on our quality scale, 452nd of 947 AI & Machine Learning skills we index (top 48%).
Its SKILL.md is 4.1 KB long, well organised into 9 sections with 5 code examples: a solid amount of guidance for an agent.
With 4,079 GitHub stars, it is one of the more widely adopted skills in the catalogue.
Maintenance, license and trust
- The repository was last updated about 2 months ago, so codex-subagent is actively maintained.
- Our last check on 2026-11-01 found the source still online.
- It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
codex-subagent compared with similar skills
All 4 of these similar skills score higher than codex-subagent; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| codex-subagent (this skill)by davidondrej | 88 | 4.1k | 53d ago | SKILL.md |
| claude-memby thedotmack | 100 | 117.6k | today | CLAUDE.md |
| Agent-Reachby Panniantong | 100 | 112.3k | 8d ago | CLAUDE.md |
| Understand-Anythingby Egonex-AI | 100 | 92.8k | 1d ago | CLAUDE.md |
| headroomby headroomlabs-ai | 100 | 79.8k | today | CLAUDE.md |
Frequently asked questions
- How do I install codex-subagent?
- Run
npx skills add davidondrej/skills --skill codex-subagent. The install tabs above show the steps for each supported agent. - Which AI agents does codex-subagent work with?
- It is written for OpenAI Codex, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is codex-subagent safe to use?
- It is MIT-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is codex-subagent still maintained?
- The repository was last updated about 2 months ago, so codex-subagent is actively maintained.
Skill content
View source on GitHubname: 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
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 \
--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 tohigh. Pass both flags explicitly on every new Codex run. - Do NOT use Codex fast mode.
</dev/nullis 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:
--jsonfor JSONL event stream.
Collect results
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 --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 statusnon-zero → the user must runcodex 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.
Related Skills
claude-mem
117.6kPersistent Context Across Sessions for Every Agent – Captures everything your agent does during sessions, compresses it with AI, and injects relevant context back into future sessions. Works with Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot, OpenCode + More
Agent-Reach
112.3kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
Understand-Anything
92.8kGraphs that teach > graphs that impress. Turn any code into an interactive knowledge graph you can explore, search, and ask questions about. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, and more.
headroom
79.8kCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
