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.

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)

mcp__codex-pair__codex-reply (Continue Session)

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.