| 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 sessionmcp__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.
