Codex Agent

The codex agent wraps OpenAI’s Codex CLI (codex binary) to execute coding tasks within your workflow. It receives a prompt assembled from the phase role and upstream context, runs Codex in quiet mode against your workspace, and captures the plain text response.

Codex CLI is OpenAI’s terminal-based coding agent powered by models like o3. As a cliq agent, it operates non-interactively — receiving its full instructions via the assembled prompt and returning results through the handoff envelope.

Sample Phase

- name: implement
  agent: codex
  role: developer
  depends_on: [architect]

Phase Configuration

The codex agent supports two phase types:

Phase Type	Description
`standard`	Code generation, implementation, refactoring, documentation
`gate`	Code review, architectural review, quality verdicts

Phase YAML Fields

Field	Type	Required	Description
`name`	`string`	Yes	Unique phase name within the workflow
`type`	`string`	No	`"standard"` (default) or `"gate"`
`agent`	`string`	Yes	Must be `"codex"`
`role`	`string`	Yes	Role file name (without `.md`) from `.cliq/roles/`
`depends_on`	`string[]`	No	Upstream phases that must complete before this phase runs
`model`	`string`	No	Model override (e.g., `"o3"`)

The role field is required — it tells the agent what persona to adopt and what kind of work to perform. Without a role, the agent has no instructions.

The model field is specified directly on the phase YAML, not in settings. This lets you use different models for different phases in the same pipeline.

Gate Behavior

When used as a gate agent, codex reviews the upstream work and produces a verdict parsed from its output:

Verdict	Meaning
`PASS`	Work meets quality bar — pipeline continues
`ROUTE`	Work needs changes — routes back to a prior phase with feedback
`ESCALATE`	Work requires human intervention — pipeline halts

Settings

Key	Required	Default	Description
`agents.codex.api_key`	Yes	—	OpenAI API key for the Codex CLI

Configure via:

echo $OPENAI_API_KEY | cliq settings agents.codex.api_key --stdin --global

Output

The codex agent writes code directly to the workspace and produces a plain text summary of the work performed. It does not produce structured data — its value is in the files it modifies and the explanation it provides.

Like the gemini agent, codex produces plain text output that cliq captures directly (not stream-json NDJSON).

Handoff Structure

{
    "data": null,
    "text": "The agent's natural language response and summary of work performed."
}

The text field is automatically injected into downstream phases’ prompts, giving subsequent agents full context of what was implemented.

Gate Output

When running as a gate phase, the handoff includes the verdict:

{
    "data": null,
    "text": "Implementation is correct. The recursive approach handles nested structures properly and the base case prevents stack overflow. PASS"
}

The orchestrator parses the verdict keyword from the response and routes the pipeline accordingly.

Examples

Example: Codex for reasoning-heavy tasks

Codex with the o3 model excels at tasks that require deep reasoning — algorithm design, complex refactoring, and architectural decisions.

phases:
    - name: implement
      agent: codex
      role: developer
      model: o3

    - name: review
      type: gate
      agent: codex
      role: reviewer
      depends_on: [implement]

    - name: finalize
      agent: git
      action: create_pr
      depends_on: [review]

Example: Codex review with a different implementation agent

Use codex as a reviewer for its reasoning capabilities while a faster agent handles implementation.

phases:
    - name: implement
      agent: cursor
      role: developer

    - name: review
      type: gate
      agent: codex
      role: senior-reviewer
      model: o3
      depends_on: [implement]

    - name: deploy
      agent: git
      action: create_pr
      depends_on: [review]

Example: Full pipeline with data fetching

A complete workflow that fetches requirements, implements with codex, and creates a PR.

phases:
    - name: fetch-ticket
      agent: jira
      action: get_issue
      sources:
          - name: ticket.json
            ref: $(inputs.ticket)

    - name: implement
      agent: codex
      role: developer
      model: o3
      depends_on: [fetch-ticket]

    - name: review
      type: gate
      agent: hug
      role: reviewer
      depends_on: [implement]
      review:
          reviewer: [tech-lead]
          artifacts:
              - src/**/*.ts
              - tests/**/*.ts

    - name: finalize
      agent: git
      action: create_pr
      depends_on: [review]

Setup

1. Install Codex CLI

npm install -g @openai/codex

Verify the binary is available:

codex --version

2. Configure the API key

echo $OPENAI_API_KEY | cliq settings agents.codex.api_key --stdin --global

3. Validate

cliq doctor agent codex

This checks that the codex binary is on PATH and the API key is configured.