Codex CLI
Generate OpenAI Codex CLI configurations from AgenTopology definitions
Codex CLI Binding
The Codex CLI binding generates configuration files for OpenAI's Codex CLI from your .at topology.
Scaffolding
agentopology scaffold my-topology.at --target codexGenerated File Structure
.codex/
agents/
researcher.md # Agent instruction file
writer.md
reviewer.md
codex.json # Main Codex CLI configuration
workflows/
code-review.json # Workflow definition for multi-agent orchestrationAgent Instruction Files
Each agent generates a markdown instruction file:
# Researcher
## Role
Research specialist in the code-review pipeline.
## Tools
- Read
- Grep
- WebSearch
## Instructions
Analyze the codebase using available tools. Gather all relevant context
before passing findings to the writer agent.Model Mapping
AgenTopology model names map to OpenAI model identifiers:
| AgenTopology | Codex CLI |
|---|---|
opus | gpt-4o |
sonnet | gpt-4o-mini |
haiku | gpt-4o-mini |
Configuration File
The main codex.json contains the CLI configuration:
{
"version": "1.0",
"topology": "code-review",
"agents": {
"researcher": {
"model": "gpt-4o-mini",
"instructions": "agents/researcher.md",
"tools": ["Read", "Grep", "WebSearch"]
},
"writer": {
"model": "gpt-4o-mini",
"instructions": "agents/writer.md",
"tools": ["Read", "Write"]
},
"reviewer": {
"model": "gpt-4o",
"instructions": "agents/reviewer.md",
"tools": ["Read", "Grep"]
}
}
}Workflow Files
Multi-agent flows generate workflow definitions that describe execution order:
{
"name": "code-review",
"pattern": "pipeline",
"steps": [
{ "agent": "researcher", "next": "writer" },
{ "agent": "writer", "next": "reviewer" },
{
"agent": "reviewer",
"next": "writer",
"condition": "verdict == 'revise'",
"maxRetries": 2
}
]
}Limitations
- Codex CLI does not natively support multi-agent orchestration. The binding generates workflow files that require a wrapper script to execute the full pipeline.
- MCP server configurations are translated where Codex CLI supports equivalent functionality.
- Hook events have limited support.
ToolUsehooks are mapped to Codex CLI's tool middleware where available. - The
scaleandmeteringblocks are not supported.