codex-build

name	codex-build
description	Use OpenAI Codex as architect and reviewer while Claude builds. Triggers on "codex build", "codex write", "codex implement", "codex fix", "pair with codex". Codex always thinks first - analyzes, plans, then reviews Claude's implementation.
allowed-tools	["Bash","Read","ToolSearch","mcp__codex-pair*"]

Codex Pair Programming Skill

Version: 6.0.0 Author: Adam Requires: Codex CLI installed and configured

The Core Idea

Codex thinks. Claude builds. Codex reviews.

Codex is the better analyzer. Claude is the better implementer. Use each for its strength. Pick the right workflow for the task size.

How to Connect (Do This First)

The Codex MCP server is registered as codex-pair. The tools are deferred and must be loaded before use:

Use ToolSearch with query: "codex-pair"

This loads two tools:

• mcp__codex-pair__codex - Start a new Codex session
• mcp__codex-pair__codex-reply - Continue an existing conversation

CRITICAL: Keep One Session Alive

USE codex-reply FOR EVERY FOLLOW-UP. The first call returns a conversationId. Use it for ALL subsequent interactions. Codex remembers every file it read, every diagnosis, every decision.

Only start a new session for a completely unrelated task.

---

Workflow

Always Architect Mode. Codex thinks first, every time.

Codex is the better analyzer. Do NOT pre-diagnose or form your own hypothesis. Send the problem to Codex raw and let it think from scratch - whether it's a one-line fix or a full feature.

Task	What Codex Does	What You Do
New feature, big refactor	Full architecture plan	Implement the plan
Bug fix, small change	Quick diagnosis + fix approach	Apply the fix
Multiple issues	Batch analysis of all issues	Implement fixes in order

Note: Validator Mode (where Claude hypothesizes and Codex validates) has been retired. Codex always goes first.

---

Workflow 1: Architect Mode

For big tasks where Codex should plan from scratch.

PHASE 1: CODEX ANALYZES (don't pre-diagnose)
   Codex reads the code, diagnoses, proposes the approach
                    |
                    v
PHASE 2: CLAUDE BUILDS
   Claude implements Codex's plan
                    |
                    v
PHASE 3: CODEX REVIEWS
   Codex verifies Claude's work, catches issues
                    |
                    v
   (repeat Phase 2-3 until Codex approves)

Phase 1: Codex Analyzes

Give Codex the problem and let it think. Do NOT pre-diagnose.

{
  "prompt": "I'm working on [project context]. The problem is: [what's wrong or what needs building]. Relevant files: [file paths]. Analyze the code, diagnose the issue, and propose an implementation plan.",
  "cwd": "/path/to/project",
  "sandbox": "read-only",
  "developer-instructions": "You are the architect. Analyze thoroughly, then propose a specific implementation plan with file paths, function names, and reasoning. Be concise but complete."
}

Send: Problem description, file paths, constraints, design references. Don't send: Your own diagnosis, line-by-line instructions, the solution you have in mind.

Evaluate Codex's plan before building. Present it to the user.

Phase 2: Claude Builds

Implement Codex's plan. Follow its architectural decisions. Use your own judgment on details.

If you realize the plan won't work mid-build, STOP and ask Codex via codex-reply before improvising. Don't silently deviate.

Phase 3: Codex Reviews

codex-reply: "I've implemented your plan. Here's what I did:
- [summary of changes]
- [any deviations and why]

Re-read the modified files and review:
1. Did I implement correctly?
2. Bugs or edge cases I missed?
3. Integrates properly with existing code?
4. Anything you'd change?"

• Codex finds issues -> fix and re-submit
• Codex approves -> present to user
• Codex suggests non-critical improvements -> present as optional to user

Report Codex's feedback honestly, including criticisms.

---

The Reframe

The highest-value Codex response isn't "yes, that's correct" or "no, change X to Y." It's: "You're solving the wrong problem. Use a completely different approach."

Examples from real usage:

• "Stop tweaking the CustomPainter opacity. Use a LinearGradient overlay instead - that's how glassmorphic buttons actually work in Flutter."
• "Don't animate secondaryAnimation directly. Use ReverseAnimation(secondaryAnimation) - your version won't affect the old route."

When Codex reframes the problem, take it seriously. That's the moment where two models catch what one model alone wouldn't.

---

General Rules

Point Codex at Files - Don't Paste Source Code

Codex reads files from cwd. Reference source files by path, don't paste their contents:

BAD: "Here's my button code: [200 lines]. What's wrong?" GOOD: "Look at lib/widgets/aethera_buttons.dart, the _InnerShadowPainter class."

Codex re-reads files between replies to see your latest edits.

Exception: Always paste git diff output when asking Codex to review changes. Diffs are change metadata, not source code - Codex needs them to see exactly what changed.

Control Verbosity

Set developer-instructions at session start:

• Small tasks: "Be concise. Diagnose the issue and propose a fix in 2-3 sentences."
• Big tasks: "Be thorough. Analyze every aspect, then propose a specific plan."

Persists across all codex-reply calls.

Parameters Reference

mcp__codex-pair__codex (Start Session)

Parameter	Required	Description
prompt	Yes	The problem or question
cwd	No	Working directory (Codex reads files from here)
sandbox	No	read-only (default) or workspace-write
model	No	Model override (e.g., o3, gpt-5.2-codex)
approval-policy	No	untrusted, on-failure, on-request, never
developer-instructions	No	Set role and verbosity

mcp__codex-pair__codex-reply (Continue Session)

Parameter	Required	Description
conversationId	Yes	ID from the first response
prompt	Yes	Follow-up message

Fallback: CLI Mode

If the MCP tools aren't available:

codex exec --sandbox read-only --full-auto "Your prompt here"

Fire-and-forget (no conversation), so prefer MCP tools.

---

Anti-Patterns

• Pre-diagnosing before asking Codex - Don't form your own hypothesis. Send the problem raw and let Codex think.
• Skipping the review phase - Always send your work back. Codex catches things you miss.
• Filtering Codex's feedback - Report it honestly to the user, including criticism.
• New session per question - Use codex-reply. One session, one conversationId.
• Pasting code instead of file paths - Codex reads files. Let it.
• Ignoring Codex's reframes - When Codex says "wrong approach entirely," listen.
• Open-ended "review everything" - Be specific. Point at files and describe the problem.