Codex bridge — direct MCP integration

What Codex is and what it brings

Codex CLI runs as an MCP server (codex mcp-server), connected to Claude Code via project-level .mcp.json plus the user-level mcpServers entry in ~/.claude.json. Authenticated via the user's ChatGPT subscription (no separate API key needed).

Binary path — one source of truth. Both registrations MUST point at the npm-global install, the same binary adversary_lg.py resolves through shutil.which("codex"):

<npm-global>/node_modules/@openai/codex/node_modules/@openai/codex-win32-x64/vendor/x86_64-pc-windows-msvc/bin/codex.exe

Resolve it once with npm root -g (or where codex / which codex) and use that same path in both registrations. Worth re-checking on a schedule: probe what the MCP client would actually launch (an initialize handshake plus tools/list), compare that binary's version against the one the consilium resolves through PATH, and confirm codex login status. A registration pointing at a binary that no longer matches is the failure this section exists to prevent.

Do NOT point them at %LOCALAPPDATA%\OpenAI\Codex\bin\codex.exe. That is the Codex desktop app's launcher; it lags the app's real binary (which lives in a per-version hash subdirectory that changes on every update), so it silently rots into an old release that rejects config keys the current app writes. That divergence is the 2026-08-27 breakage: codex exec kept working on the npm binary while the MCP server died on the stale one, taking every visual specialist offline without touching the adversary consilium. See memory/codex-mcp-config.md for the diagnostic sequence.

Through MCP, two tools are exposed:

• mcp__codex__codex — start a Codex session with prompt + config
• mcp__codex__codex-reply — continue a thread by id + new prompt

Underlying model: whatever model is set to in ~/.codex/config.toml — currently gpt-6-astra. The agency deliberately does NOT pin a model at the call site (neither adversary_lg.py nor any workflow passes one), so one config line moves both the MCP and the codex exec path together. Capabilities:

• Image generation and editing (DALL-E 3 / gpt-image-1 class)
• Web lookup
• PowerShell shell access (read-only by default, configurable)
• Local image viewing (multimodal vision)
• MCP resource reading
• Sub-agents (only on explicit delegation)

Codex as the default creative director for visual work

For ANY visual-creative deliverable — logo / brand identity, hi-fi UI visuals, campaign banners, presentation slide visuals, photography / imagery, art direction, "give me N bold directions" — Codex is the default creative engine, not a fallback or an afterthought. The Claude specialist does NOT hand-author the visual concept; it ORCHESTRATES Codex and integrates the result.

Division of labour (the standing default for every design/visual engagement — baked into the visual agents + their methodology skills, NOT a per-engagement choice):

Why: this Claude model family is comparatively weak at visual-creative divergence; Codex / ChatGPT (gpt-image class) is stronger and more interesting. The creative idea comes from Codex; Claude conducts and builds.

Graceful fallback (never a silent quality downgrade): if Codex is offline or quota-exhausted, fall back to Gemini (the design-assets-guide / banner-design-guide scripts) or escalate to the user — and SAY the creative path was downgraded. Do not quietly substitute a weaker Claude-authored visual and present it as the intended quality.

The ## When to use Codex table below is the per-deliverable routing UNDER this default (structural / data-driven / tokenizable work stays Claude; SVG icons may stay Gemini). Read it as "when does a fallback or a structured-Claude path apply", not "should I use Codex at all for the creative".

When to use Codex (vs Gemini, vs Claude tools, vs static SVG)

Rule of thumb: if the deliverable benefits from photorealism, complex visual composition, or cross-family second opinion, use Codex. If structural / data-driven / tokenizable, use Claude tools.

Direct invocation pattern

Specialist agent calls the MCP tool directly. The tool spawns a fresh Codex session, sends the prompt, returns the result.

Image generation — basic call

# Pseudocode for tool call structure (the actual call is via MCP tool invocation)
mcp__codex__codex({
    "prompt": (
        "Generate a 1024x1024 PNG: minimalist FinTech logo, "
        "blue (#0066cc) circle with white inner geometric mark, "
        "flat style, no text. "
        "Save to engagement/codex-outputs/logo-v1.png. "
        "Output one line: SAVED: <path>"
    ),
    "approval-policy": "never",
    "sandbox": "workspace-write",
    "cwd": "/path/to/working/dir"
})

Codex will:

1. Generate the image using its internal image-gen tool
2. Save to the specified path (path must be under cwd if sandbox: workspace-write)
3. Reply with SAVED: <path> confirmation

Required arguments

Multi-turn refinement

For iterative work (refine output, generate variants):

# First call returns a thread id in the response
result = mcp__codex__codex({...})
thread_id = parse_thread_id(result)

# Subsequent refinements use codex-reply
mcp__codex__codex-reply({
    "threadId": thread_id,
    "prompt": "Variant 2: same composition but with a square mark instead of geometric inner shape."
})

The parameter is threadId. conversationId still works but its own schema marks it DEPRECATED. There is no thread_id argument: the schema declares only prompt as required, so a snake_case key is dropped silently and the call opens a session that never saw the first prompt. That reads as "Codex ignored the refinement", not as an error. Re-probe the live schema (codex mcp-server, tools/list) after a Codex update rather than trusting this line.

Engagement integration: codex-outputs/ artefact

Generated assets live in engagement/codex-outputs/ (whitelisted directory). Specialist agent:

1. Calls mcp__codex__codex with cwd=engagement/ and explicit save path under codex-outputs/.
2. Verifies the file exists via Read tool (multimodal — confirms image roughly matches prompt).
3. Logs in engagement/validation-log.md under specialist's section:

   ### codex-bridge invocations (iter N)
   - logo-v1.png (1024x1024 PNG, prompt: "minimalist FinTech logo...") — verified ✓
   - banner-instagram-v1.png — verified ✓ (3 variants requested via codex-reply)

4. Integrates the asset into the deliverable (handoff §2 or domain-specific dir).

Vision review (multimodal)

Codex can look at images and judge them — useful for design review where Claude's text-based reasoning misses visual issues:

mcp__codex__codex({
    "prompt": (
        "Look at the screenshot at engagement/screens/iter-1/dashboard-dark.png "
        "and the criteria from engagement/criteria.md. List 3 specific UX issues "
        "you observe in the screenshot, with severity. Be concrete about where in "
        "the image (top-left, center, etc.). Output JSON only."
    ),
    "approval-policy": "never",
    "sandbox": "read-only",
    "cwd": "/path/to/engagement"
})

Codex returns structured findings the agent can integrate into validation-log.md or pass to consilium-synth.

Cross-family coverage map (where Codex IS and is NOT used)

Why this map matters: the audit (agency_chains_audit.md Section E) initially suggested promoting Codex to standard cross-family validator at L-tier. On review, this duplicates what L-tier adversary already does: adversary on L runs 2 Codex reviewers seeing the same artefacts validators saw. The Codex cross-check happens — just at the adversary stage, not the validator stage. Adding a second Codex pass at validator level would burn budget without adding signal.

The one genuine gap: the director's JUDGE phase is single-family even on L-tier. The supreme-judge (human) step partially compensates by introducing a third viewpoint, but if you want truly cross-family adjudication, a future director_lg.py could include an optional Codex co-adjudicator on the L-tier verdict. Not implemented now — flagged as Wave 4+ opportunistic per migration roadmap.

Adversary integration (cross-family second opinion)

adversary_lg.py already supports codex-blind and codex-informed reviewer roles via subprocess invocation. With MCP available, an alternative path is to call mcp__codex__codex directly from a specialist agent's review workflow:

# Cross-family adversary review of a deliverable
mcp__codex__codex({
    "prompt": (
        "You are an adversarial reviewer. Read engagement/criteria.md and "
        "engagement/handoff.md. Find what is wrong, missing, or insufficient. "
        "Output JSON: {verdict: satisfied|rework_required|suspicious_too_clean, "
        "findings: [...], summary: '...'}."
    ),
    "approval-policy": "never",
    "sandbox": "read-only",
    "cwd": "/path/to/engagement"
})

This is functionally equivalent to adversary_lg.py --role codex-blind but with native MCP tool integration (no Python subprocess overhead).

Anti-patterns

• Don't pass model at all. The ChatGPT subscription serves only some ids, and a call naming one it does not serve fails outright. Set the model once in ~/.codex/config.toml; every call inherits it.
• After changing the model, restart the session. The MCP roster is fixed at session start, so a running session keeps the binary it started with — and a model newer than that binary fails per-invocation with "requires a newer version of Codex" even though the config is correct.
• Don't use sandbox danger-full-access unless engagement explicitly requires write outside engagement/ (extremely rare).
• Don't generate images directly into engagement/brand/ or engagement/ui/ — pair structure: generate to engagement/codex-outputs/, then specialist promotes to final location after verification.
• Don't skip the verification step — agent must Read the generated image and confirm it roughly matches the prompt before integrating.
• Don't accept "looks close enough" — if output doesn't satisfy acceptance criteria, refine via codex-reply (max 3 refinement rounds before escalating).
• Don't put Codex prompts in handoff.md prose — they're embedded in tool calls; audit trail goes to validation-log.md.
• Don't expect Codex to know your engagement context — every call is fresh; pass full criteria/constraints in the prompt.

Iteration on Codex outputs

If output doesn't satisfy criteria after first call:

1. Call mcp__codex__codex-reply with threadId and refinement prompt.
2. Max 3 refinement rounds per asset before escalating to user (or trying alternative tool, e.g. Gemini).
3. Each refinement round logged in validation-log.md with ## Refinement N heading and brief delta.

Permissions and approval

Codex tools (mcp__codex__codex, mcp__codex__codex-reply) need to be allowlisted in Claude Code permissions for unattended use. First invocation will prompt for approval per Claude Code's MCP permission UX. Once approved, subsequent calls in the same session run without prompts.

For automated agency engagements, consider adding to user settings.json permissions.allow:

"mcp__codex__codex",
"mcp__codex__codex-reply"

Cost and rate limits

Uses ChatGPT subscription quota. No separate billing if subscription is active. If quota exhausts mid-engagement, Codex returns an error response — specialist agent should detect, log, and either fall back to alternative tool (Gemini) or escalate to user.

Quick reference

Tool name (MCP):         mcp__codex__codex
Continue same session:   mcp__codex__codex-reply (with threadId)
Binary both paths use:   %APPDATA%\npm\node_modules\@openai\codex\...\bin\codex.exe (npm-global)
Health check:            codex login status  →  "Logged in using ChatGPT", exit 0
                         echo '{"jsonrpc":"2.0","id":1,"method":"initialize", ...}' | codex mcp-server

Must-pass args:          prompt, approval-policy, sandbox, cwd
Don't pass:              model (set it in ~/.codex/config.toml instead)

Where outputs go:        engagement/codex-outputs/{slug}.png
Audit log:               engagement/validation-log.md → ## codex-bridge invocations
Refinement budget:       3 rounds per asset