Codex Orchestration

Cross-Model Orchestration — Claude + Codex + Antigravity (agy)

Delegate tasks to Codex CLI (GPT-5.6-sol) and the Antigravity CLI (agy) from Claude Code for second opinions, parallel research, challenger reviews, and idea generation. Each model runs as an independent agent with its own context, tools, and reasoning — different models catch different things.

Codex Plugin Commands (Primary Interface)

The Codex plugin (codex@openai-codex) provides first-class slash commands for structured Codex interaction. Prefer plugin commands over raw codex exec for reviews, task delegation, and managed workflows.

When to Use Plugin vs Raw codex exec

Plugin commands handle job lifecycle (tracking, resume, cancel). Raw codex exec is better for parallel orchestration and custom prompt engineering.

Antigravity CLI (agy) — Primary Interface

The Antigravity CLI (agy) is this host's second-opinion / challenger / research delegate. It authenticates itself via the Antigravity account — no API key or env prefix needed. There is no MCP server: call agy directly via Bash. See the antigravity-cli skill for the full reference.

Headless single-prompt mode:

timeout 600 agy --sandbox -p "<prompt>" < /dev/null

• STDIN RULE (mandatory, #135): < /dev/null on every headless agy call — agy reads non-TTY stdin until EOF before the model call; background/harness shells never EOF → infinite hang at 0 bytes (--print-timeout does not protect; it guards only the print phase). Piped input (cat file | agy -p) is safe (the pipe EOFs). Always wrap in shell timeout. Same behavior class as codex exec's stdin-block.
• FLAG ORDER RULE (mandatory, root-caused 2026-07-02): every flag BEFORE -p, prompt LAST. -p is a string flag and consumes the next token — agy -p --sandbox "X" runs UN-sandboxed with the literal prompt --sandbox and discards "X", after which agy improvises from its implicit memory (the "does work instead of consulting" failure mode) and can fork-bomb re-testing the broken command. Correct: agy --sandbox [--add-dir D] [--print-timeout 15m] -p "…".
• SANDBOX RULE (mandatory for analyst/read-only delegation, #157): --sandbox on every agy call that should only READ — agy has write/shell/git tools by default, and an un-sandboxed "analyst" can author and git-commit code (S052 rogue auto-commit incident). Scope caveat (verified 2026-07-02, 1.0.15): --sandbox constrains shell/git commands only, NOT agy's native file writes — do not --add-dir a writable live repo for consultancy (pipe content instead), open the prompt with "Advisory only — do not modify any files; answer on stdout", and run git status --short afterwards if a repo was exposed. Omit --sandbox only when the task explicitly requires writes, and say so in the prompt.
• Output is plain text on stdout — there are no structured response fields. Callers must parse text, not JSON.
• agy uses the Antigravity-account default model by convention — as of 1.0.5+ (current 1.1.6) a --model flag and an agy models subcommand DO exist (there is no short -m alias), but omit --model unless a call explicitly needs a specific model. The account default is gemini-3.6-flash (verified 2026-07-24), so omitting the flag rides the current line automatically. FLASH-ONLY HARD-RULE (user directive 2026-07-24): agy runs gemini flash models ONLY. ✅ gemini-3.6-flash-{high,medium,low} (current) / gemini-3.5-flash-* (legacy). ❌ FORBIDDEN with no carve-out: claude-sonnet-4-6, claude-opus-4-6-thinking, gpt-oss-120b-medium, and gemini-3.1-pro-{high,low}. Reasons: (1) provider diversity — agy holds the third-model slot because it is neither Anthropic nor OpenAI; repointing it at claude-sonnet-4-6 (the tempting "fix" for an agy no-show) collapses the cross-check into an echo, and gpt-oss-* collapses into the Codex arm; (2) flash-tier discipline — agy is advisory-tier, so don't reach for pro. On a no-show: retry under the STDIN/FLAG-ORDER/Pattern-2 rules, then record the provider gap honestly — there is no gemini fallback (retired 2026-07-25). Escalate to another arm rather than repointing agy.
• For long-running prompts raise the wait timeout: agy --print-timeout 15m -p "<prompt>" < /dev/null (default 5m0s). Keep < /dev/null even here — --print-timeout only guards the print phase, NOT the stdin read, so omitting it still hangs to the shell timeout (#135).
• Append a served_by probe line to the prompt if you need provenance — self-reported model identity is unreliable, so capture it at the call layer.

Use cases (all via a single agy -p call): research, analysis, code review, large-file analysis, and brainstorming (frame the methodology — SCAMPER, Design Thinking, Divergent, Convergent, Lateral — directly inside the prompt text, since there is no dedicated brainstorm tool).

agy -p invocation patterns

# Basic headless mode (plain-text stdout — no JSON output mode)
agy --sandbox -p "Review this code for security issues" < /dev/null

# With piped context
cat src/main.py | agy --sandbox -p "Find N+1 query problems"

# Reference a workspace directory instead of piping (repeatable)
# CAUTION: --sandbox does NOT gate native file writes into --add-dir trees — prefer piping;
# if you must --add-dir a writable repo, run `git status --short` afterwards and revert strays.
agy --sandbox --add-dir "$PROJECT_DIR" -p "Advisory only — do not modify any files; answer on stdout. Review for security issues in this project" < /dev/null

# Structured brainstorming — frame the methodology inside the prompt
agy --sandbox -p "Use SCAMPER to generate ideas for reducing checkout abandonment. List each lens separately." < /dev/null

# Parallel with Codex (triple-model validation)
CODEX_WORK=$(mktemp -d /tmp/codex-XXXXXXXXXX)
AGY_WORK=$(mktemp -d /tmp/agy-XXXXXXXXXX)

timeout 600 codex exec --ephemeral -C "$PROJECT_DIR" -s read-only \
  -o "$CODEX_WORK/review.md" "Review for security issues" < /dev/null &
timeout 600 agy --sandbox --add-dir "$PROJECT_DIR" -p "Review for security issues in this project" \
  > "$AGY_WORK/review.txt" < /dev/null &
wait

agy Availability Check

AGY_AVAILABLE=$(agy --version 2>/dev/null && echo "yes" || echo "no")

Cache for the session like the Codex check. Both can be checked in parallel at session start.

Reasoning-Effort Tiers (benchmarked 2026-07-11)

Measured on gpt-5.6-sol / codex-cli 0.144.1 with planted-bug review fixtures (14 scored runs, easy + hard rounds + a delta-seeking challenger round). Every tier found all planted bugs with zero false positives; the only quality separations were (a) one subtle unplanted defect caught only at xhigh/max under a plain review prompt, and (b) finding ALTITUDE under a delta-seeking prompt — medium returned concrete-bug deltas, xhigh added state-consistency reasoning, max alone produced a design-level finding. high never beat medium in any run — skip it. ultra matched max's findings at 2.3x the time on bounded tasks; it exists for orchestrated deep dives, not verdicts.

# Challenger call — xhigh floor, effort pinned per call
timeout 600 codex exec --ephemeral -s read-only \
  -c model_reasoning_effort=xhigh \
  -o "$CODEX_WORK/challenge.md" "$(cat "$CODEX_WORK/brief.md")" < /dev/null

Delta-seeking challenger prompt (the honest-loop contract). Prompt shape matters as much as tier: telling codex "the basics are done" reallocates attention to the tail — at medium this recovered a subtle bug that a plain review prompt missed even at high. Template to embed in challenger briefs:

A prior review already found: <findings list>. Your ONLY job: find genuine defects the prior review MISSED. Do not repeat, rephrase, or elaborate on listed findings. Inventing a finding to have something to say is a failure mode; if you find nothing genuinely new, output exactly: NONE_FOUND

Operational notes:

• Retry ONCE on Selected model is at capacity (transient; fails within ~2s, so the retry is cheap).
• Keep -s read-only on every consultancy call: at max, codex has run unrequested read-only shell detours (reading its own skill files) despite an explicit "do not browse the filesystem" instruction — the sandbox contained it.
• max/ultra workflow stages need raised timeouts (1200s/1800s), not the default 600s.

Three-Model Validation Pattern

For COMPLEX tasks, run all three models for maximum coverage:

Diverge → Challenge → Converge:

1. Claude explores approaches (via forge design team)
2. Codex challenges (via /codex:adversarial-review or raw exec)
3. agy independently analyzes (via agy -p)
4. Claude synthesizes — flag agreements (high confidence) and disagreements (investigate)

Current State (verified 2026-07-11)

System Configuration

# ~/.codex/config.toml (as of 2026-07-11) — effort levels for gpt-5.6-sol:
# low | medium (TUI default) | high | xhigh | max | ultra
model = "gpt-5.6-sol"
model_reasoning_effort = "max"   # TUI-persisted; do NOT rely on it — pin per call

Model Override

The interactive /model picker persists both model and model_reasoning_effort into config.toml, and headless codex exec inherits both. Omit -m in delegation calls (inherit the configured model) and pin only the EFFORT per call. Use -m solely when a task explicitly needs a different model than the configured default.

Cross-Model Advantage

Claude Fable 5 and GPT-5.6-sol have different strengths. Use both:

Key principle: Use Codex for tasks where a different model's perspective adds value — challenger reviews, second opinions, independent research. Don't use it as a replacement for Claude's tool ecosystem.

New since 0.118 (subcommands added through 0.137.0)

The Codex CLI grew several subcommands between 0.118 and 0.137. Most are experimental backend services, not day-to-day delegation entry points — codex exec and the plugin commands remain the orchestration surface. Confirm any of these with codex <sub> --help before relying on it.

(Also present but already documented elsewhere in this skill: archive / unarchive for saved sessions, mcp-server to run Codex itself as an MCP server, completion for shell completions.)

Core Integration: codex exec

The key command for non-interactive delegation:

codex exec [OPTIONS] [PROMPT]
# Or pipe prompt via stdin:
echo "prompt" | codex exec -

# Critical flags:
#   --ephemeral                    Don't persist session
#   --skip-git-repo-check          Allow running outside git repos
#   -o, --output-last-message FILE Write final response to file
#   --json                         Stream JSONL events to stdout
#   --output-schema FILE           Enforce structured JSON output
#   -m, --model MODEL              Override model (default: from config; currently gpt-5.6-sol)
#   -c KEY=VALUE                   Config override — used for per-call effort pins
#                                  (-c model_reasoning_effort=medium|xhigh|max|ultra)
#   -C, --cd DIR                   Set working directory
#   -s, --sandbox MODE             read-only | workspace-write | danger-full-access
#   --full-auto                    Sandboxed auto-execution
#   -i, --image FILE               Attach image(s)
#
# Note: `--search` does NOT exist as a flag in current Codex CLI (verified 2026-04-08).
# Codex web search is enabled automatically by GPT-5.x tool use when the sandbox allows it.
# Earlier versions of this skill mentioned --search; that was incorrect.

Session Directory (REQUIRED)

# Create ONCE per Codex delegation block — reuse for all tasks in that block
CODEX_WORK=$(mktemp -d /tmp/codex-XXXXXXXXXX)

# All briefs, results, schemas, and events go under $CODEX_WORK/
# The directory is unique per invocation — no collision possible

Basic Delegation Pattern

CODEX_WORK=$(mktemp -d /tmp/codex-XXXXXXXXXX)

# Delegate a research task, capture output
timeout 600 codex exec --ephemeral --skip-git-repo-check \
  -o "$CODEX_WORK/research-output.txt" \
  "Research the top 5 approaches to container orchestration for single-node production deployments." < /dev/null

# Read the result back into Claude Code
# Read: $CODEX_WORK/research-output.txt

Session-Scoped Availability

Check Codex once per session, cache the result:

CODEX_AVAILABLE=$(codex --version 2>/dev/null && echo "yes" || echo "no")

All subsequent checks in the session read this variable instead of re-running the command. Forge step 4b and all other callers should reference this pattern.

Full Availability Check (When Needed)

check_codex() {
  if ! command -v codex &>/dev/null; then
    echo "UNAVAILABLE: codex not installed"
    return 1
  fi

  # Quick test (timeout after 10s)
  if ! timeout 10 codex exec --ephemeral --skip-git-repo-check \
    -o /dev/null "Reply OK" < /dev/null 2>/dev/null; then
    echo "UNAVAILABLE: codex auth/subscription issue"
    return 1
  fi

  echo "AVAILABLE"
  return 0
}

Sandbox Modes

When to Delegate to Codex vs Keep in Claude

Shared Skill Library

Claude skills are symlinked into Codex's skill directory (~/.codex/skills/). Codex has access to 112 shared reference skills plus its own 7 native skills (119 total). Claude has 119 skills total.

Symlink structure: ~/.codex/skills/<name> -> ~/.claude/skills/<name>

Skills NOT shared (Claude-specific): agent-teams, codex-orchestration, forge, vertex-banana, vertex-banana, research-for-skills, challenger (Codex has native challenger-review).

Naming note: Claude's challenger skill = Codex's challenger-review skill. Both provide the same framework from different model perspectives.

Reference Files

For advanced patterns, templates, and examples, see:

• patterns.md — handover patterns, progress tracking, skill injection, multi-file output, streaming
• templates.md — ready-to-use brief templates for challenger, approach explorer, research, escalation, prototyping, code review

Anti-Patterns

Related Skills

Verified facts (verified 2026-06-05)

Gotchas