CodexLog

Appearance

Split-Role "Sub-Agents" (Codex CLI) ​

Short answer: Codex doesn't expose a first-class "sub-agent" object the way some tools market it—but you can reliably simulate role-based sub-agents with (a) parallel Codex Cloud tasks (each in its own sandbox), (b) multiple CLI runs (codex exec) scoped to different goals, and (c) directory- or file-scoped guidance in AGENTS.md for role discipline. Codex officially documents isolated per-task containers in Cloud, approval-gated edits in the CLI, and AGENTS.md as a README-for-agents that constrains behavior. (OpenAI Developer)

Two practical patterns ​

1) Manual orchestration (multi-perspective jobs) ​

Launch separate tasks, each framed as a specific "role" in its prompt. In Cloud, every task runs in its own container, so analyses can proceed in parallel without shared state; in the CLI, codex exec "…" spawns isolated non-interactive runs you can queue from your shell or CI. Use read-only / ask flows for analysis, then run a follow-up task to consolidate conclusions. (OpenAI Developer)

Examples (analysis only): • "Security reviewer: audit src/auth.ts for common vulns; no edits, summarize risks & fixes." • "Performance reviewer: profile cache layer and suggest concrete micro-optimizations; no edits." • "Type safety reviewer: check src/utils.ts for unsafe any and propose typed refactors; no edits."

Why this works: Cloud tasks are explicitly described as background, parallel jobs, each provisioned into a new sandbox with your repo, dependencies, and environment. You can trigger them from web/IDE/iOS/GitHub and review the artifacts later. (OpenAI Developer)

2) Custom "roles" via AGENTS.md ​

Codex can be guided by AGENTS.md files in your repo. You can give different subtrees different instructions and invariants (e.g., "security-reviewer rules" vs "UX-reviewer rules"). The scope & precedence of AGENTS.md are spelled out in OpenAI's Codex post: deeper files override shallower ones and the file's scope is its directory tree. (OpenAI)

Minimal AGENTS.md (role: security reviewer)

markdown
# Role: security-reviewer
## Invariants (DO NOT change)
- No code edits in analysis mode.
- Report: risks, repro steps, CVE/class names, minimal fix outline.
## Checks
- Run: `npm test -- --selectProjects security`
- Grep for: `eval\\(|child_process|execFile\\(`
## Output format
- Numbered findings + severity + rollback advice

Safety rails while you split roles ​

  • Approval modes (CLI). Start in Read Only via /approvals to force plan/analysis; escalate to Auto only when ready to apply minimal diffs; Full Access is available but risky (e.g., network/out-of-dir access requires care). (OpenAI Developer)
  • Ask vs Code (Cloud). Use ask for multi-role analysis; use code only when ready to apply changes. Each mode has distinct scope/precedence rules. (OpenAI)

Workflow: multi-role analysis → consolidation → execution ​

  1. Define roles in AGENTS.md. Security/Performance/TypeSafety rules with explicit scope/precedence. (OpenAI)
  2. Spawn N role tasks (Cloud). "Security/Perf/Types" in ask mode, in parallel. (OpenAI Developer)
  3. Consolidation task. Launch a follow-up ask task: "Synthesize the three reports; propose a single risk-ranked plan."
  4. Apply diffs (CLI or Cloud code mode). Switch one session to Auto (CLI) or code (Cloud) to implement the approved plan with minimal diffs and test evidence. (OpenAI Developer)

What Codex does not provide (and how to work around it) ​

  • No first-class "sub-agent" objects. Official docs describe tasks & containers, not named sub-agents. Use parallel tasks and scoped AGENTS.md instead. (OpenAI Developer)
  • No per-task tool policy UIs (yet) in CLI. You can limit tools via MCP configuration and approval modes; consult the open-source CLI README/issues for current config patterns. (GitHub)

Why multi-role helps ​

Running independent, role-targeted analyses avoids cross-talk in a single long thread and surfaces complementary evidence (security, performance, type safety) you'd likely miss serially. Because Cloud tasks are parallel and sandboxed, you get breadth without slowing the main thread; then you merge results with a single consolidation pass. (OpenAI Developer)

Sources ​

  • Codex Cloud — per-task sandboxes; background & parallel tasks; ask/code modes; delegation surfaces. (OpenAI Developer)
  • Codex CLI — approvals (/approvals), non-interactive exec, model switching. (OpenAI Developer)
  • Introducing Codex — AGENTS.md guidance; scope & precedence rules. (OpenAI)
  • AGENTS.md repo (OpenAI) — "README for agents" format and examples. (GitHub)
  • MCP support (CLI README) — configure MCP servers via ~/.codex/config.toml. (GitHub)