Sub-agents in Codex

~12 min · codex, subagents, delegation

Level 0🌱 Novice

0 XP0/70 lessons0/11 achievements

0/120 XP to next level120 XP to go0% complete

Specialized agents under Codex

Codex supports sub-agents (experimental as of early 2026): named, scoped agents the parent Codex delegates to. The shape mirrors Claude's: a YAML-frontmatter markdown file declaring the sub-agent's role, tool allowlist, and system prompt. Lives in .codex/agents/ (project) or ~/.codex/agents/ (user).

Enable via features.sub_agents = true in config.toml. The parent calls sub-agents with natural-language delegation: "Use the security-reviewer to audit src/auth.ts."

Code

A read-only security sub-agent·markdown

---
name: security-reviewer
description: |
  Security-focused review. Auto-delegated when the user asks
  about security, vulnerabilities, auth, or data handling.
model: gpt-5-codex
tools:
  - Read
  - Grep
  - Glob
tool_denylist:
  - Edit
  - Write
  - Bash
---

You are a senior application security engineer. Audit only, never
modify. Always cite the CWE class. Format findings as:
[SEVERITY] desc (file:line) — CWE-XXX

Enable + use·toml

# ~/.codex/config.toml
[features]
sub_agents = true

# In a session:
# "Use the security-reviewer to audit src/auth.ts and
#  the perf-reviewer to scan src/db/."

External links

Codex sub-agents (experimental)

Exercise

Define a Codex sub-agent for a recurring scoped task. Enable sub-agents in config. Delegate from the parent Codex with a natural-language ask. Note how context isolation feels different from a single-agent run.

Progress

Progress is local-only — sign in to sync across devices.

← PreviousScripting with codex exec Next →Codex Cloud — Tasks That Outlive Your Terminal

Spotted a bug or have feedback on this page?Report an Issue

Comments 0

🔔 Reply notifications (sign in)

No comments yet — be the first.