How can I create custom agents (e.g., Review, Test, Refactor) using the Codex CLI?

[grandimam]

Hi everyone

I have been experimenting with the OpenAI Codex CLI, and I would like to build a setup similar to Claude Code, where I can define multiple specialized agents — for example:

• Review Agent – analyzes code for bugs, style, and security issues
• Test Agent – generates or updates unit tests
• Refactor Agent – improves readability or structure while preserving functionality

My goal is to orchestrate these agents in sequence (e.g., review → refactor → test), possibly using shell scripts or the Agents SDK.

What I’d love to know is:

• What’s the best way to define and run custom Codex CLI profiles or roles for each agent?
• Can I script multi-step workflows using the CLI alone, or should I integrate it with the Agents SDK?
• Are there any recommended patterns for sharing context between CLI runs (like passing review output to a refactor agent)?

Has anyone built something similar and can share examples or configuration tips? Any guidance, example workflows, or repo links would be really appreciated.

Thanks in advance!

[am-will]

subagents are a feature OAI is working on.

[grandimam]

Thanks.

[BoltzmannEntropy]

You can use something like this: https://github.com/obra/superpowers/blob/main/docs/README.codex.md

[guidedways]

Another option: #7296

Plus you can try and use saved prompts. I use them to great effect.

[realruian]

Update: this is now built into Codex. Current releases support subagents and named custom agents, so this workflow does not need shell wrappers or the Agents SDK for the normal local case.

Define project-scoped agents as standalone TOML files under .codex/agents/ (or ~/.codex/agents/ for personal agents). For example:

# .codex/agents/reviewer.toml
name = "reviewer"
description = "Reviews code for correctness, security, and test risks."
sandbox_mode = "read-only"
developer_instructions = """
Review the requested diff. Do not edit files.
Return prioritized findings with file/line evidence and a short handoff.
"""

Create equivalent refactorer.toml and tester.toml files with role-specific instructions and sandbox settings. Codex also ships with default, worker, and explorer agents.

Then use one parent Codex session as the orchestrator:

Review this branch against main.
1. Have reviewer produce prioritized findings.
2. Pass only the accepted findings to refactorer and let it implement them.
3. Have tester run the relevant checks and report regressions.
Return one final summary with the changes and test results.

For context sharing, the cleanest pattern is:

• keep repository-wide conventions in AGENTS.md;
• keep role behavior in each agent TOML file;
• let each subagent return a concise handoff to the parent, which passes the relevant result to the next agent;
• use files/JSON artifacts when the output must survive separate CLI invocations.

The Agents SDK becomes useful when an external program must control the graph deterministically, persist state, stream events, or implement retries. For a review → refactor → test flow inside one repo, native Codex subagents are now the simpler option.

Official docs: https://developers.openai.com/codex/subagents