AgenTopology

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 codex

Generated 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 orchestration

Agent 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:

AgenTopologyCodex CLI
opusgpt-4o
sonnetgpt-4o-mini
haikugpt-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. ToolUse hooks are mapped to Codex CLI's tool middleware where available.
  • The scale and metering blocks are not supported.

On this page