Codex: Expert
At the top level you stop driving one session and start orchestrating many: subagents, cloud tasks in parallel, and Codex wired into scripts and CI. The constraint shifts from “what can Codex do” to “how do I run it safely at scale.”
Subagents
Section titled “Subagents”Define custom agents as TOML files in ~/.codex/agents/ (personal) or .codex/agents/ (project). Required fields: name, description, developer_instructions. Optional ones (model, model_reasoning_effort, sandbox_mode, mcp_servers, skills.config) inherit from the parent when omitted. Concurrency is capped by agents.max_threads (default 6) and nesting by agents.max_depth (default 1).
A complete agent file:
name = "reviewer"description = "Diff reviewer focused on correctness, security, and missing tests."model_reasoning_effort = "high"sandbox_mode = "read-only"developer_instructions = """Review the diff like an owner. Flag correctness bugs, security issues,and missing tests. Cite file and line for every finding. No style nits."""Splitting work across focused subagents beats one over-stuffed session: each gets its own clean window instead of fighting for the same ~258K tokens. (Project-scoped agents load only in trusted projects; see Advanced.)
Run tasks in the cloud, in parallel
Section titled “Run tasks in the cloud, in parallel”Codex cloud (chatgpt.com/codex) runs background tasks on OpenAI-hosted machines and hands back a PR for the commit step. Kick off several at once instead of serializing them, and review the PRs as they land. Automations run threads on a schedule; Codex access tokens (2026-05-05, ChatGPT Enterprise) enable non-interactive auth for them.
Script it with codex exec
Section titled “Script it with codex exec”codex exec is the headless mode: it streams progress to stderr, prints the final message to stdout, and exits cleanly for piping. Useful flags:
| Flag | Purpose |
|---|---|
--json | Emit JSONL events for parsing |
--output-schema <path> | Constrain output to a schema |
-o, --output-last-message <file> | Write the final message to a file |
--ephemeral | Run without writing session files |
--ignore-user-config | Ignore ~/.codex config for a reproducible run |
--skip-git-repo-check | Run outside a git repo |
codex exec resume --last | Continue the previous headless run |
Pair --json or --output-schema with a downstream parser and you have a building block for pipelines: Codex does the work, your script reads structured results and decides what happens next.
Composed into something runnable, using the reviewer agent above: the JSONL stream emits thread.started, turn.*, and item.* events, and the final agent message arrives as an item.completed event you can extract with jq.
codex exec --ephemeral --sandbox read-only --json \ "As the reviewer agent, review the uncommitted diff and list findings" \ | jq -r 'select(.type == "item.completed" and .item.type == "agent_message") | .item.text'Everything else on the stream (commands run, files read) stays available for logging; your script sees only the findings.
Wire it into CI
Section titled “Wire it into CI”The official openai/codex-action@v1 GitHub Action installs the CLI, starts a Responses API proxy when given an API key, and runs codex exec with your prompt, sandbox, and safety strategy (default drop-sudo).
You’re done when…
Section titled “You’re done when…”- ✅ You’ve split a task across subagents or parallel cloud tasks
- ✅
codex execruns in at least one script or pipeline - ✅ Your CI uses codex-action with secrets kept out of untrusted checkouts
Next step
Section titled “Next step”You’ve reached the top of the Codex track. The habits that scale (steering, verification, a clean window) are the same ones the Foundations are built on.