Codex Mentor

Claude Code acts as the orchestrator; Codex acts as the mentor / reviewer. The skill runs discussions, consensus-building, and reviews autonomously — without prompting the user for intermediate confirmation.

Prerequisites

Codex CLI must be installed and the codex command must be available. Works via MCP server or direct CLI invocation.

Invocation priority:

1. MCP tool codex is available → call via MCP
2. MCP unavailable → run codex exec --full-auto -q "prompt" in bash

Check which method is available before the first call.

Three Modes

This skill has three modes. Determine the appropriate mode from the user's instruction.

1. Discussion (Design Debate / Sparring)

For decisions with no single right answer — architecture choices, technology selection, design trade-offs.

Trigger examples: "discuss the design", "I want to spar on this", "which approach is better"

Protocol:

1. Propose — Claude summarizes the current context and presents a recommendation
2. Challenge — Send the proposal to Codex requesting critical review, alternatives, and blind-spot identification
3. Synthesize — Incorporate Codex's feedback and revise the proposal
4. Verify — Present the revised proposal to Codex and confirm no critical concerns remain
5. Conclude — Summarize the consensus and report to the user

Cap at 3 rounds. If consensus is not reached, present both positions side by side.

2. Review (Code Review)

Request a review of existing code or diffs from Codex, then apply fixes.

Trigger examples: "review this code", "get Codex to review", "run a review loop"

Protocol:

1. Prepare — Collect code and diffs under review (git diff, file reads, etc.)
2. Review — Send code and context to Codex requesting review on:
   • Bugs and logic errors
   • Performance concerns
   • Readability and maintainability
   • Security risks
   • Design improvements
3. Triage — Classify Codex's findings by severity (critical / warning / suggestion)
4. Fix — Claude fixes all critical and warning items
5. Re-review — Send the fixed code back to Codex for verification
6. Report — Report the final result to the user (fixes applied, remaining suggestions, etc.)

Repeat Fix → Re-review as long as critical findings remain (max 3 rounds).

3. Mentor (Advice / Sanity Check)

Validate an approach or ask for best practices before starting implementation.

Trigger examples: "I want a second opinion", "ask the mentor", "does this approach make sense"

Protocol:

1. Ask — Claude organizes the current task, approach, and open questions, then sends them to Codex
2. Receive — Receive Codex's response
3. Evaluate — Claude examines the response; if follow-up is needed, send one additional question
4. Apply — Present the final approach (incorporating advice) to the user and proceed to implementation

Prompt Template for Codex

Structure all prompts sent to Codex as follows:

You are acting as a mentor/reviewer for a coding project.

## Context
{Project overview, tech stack, relevant file structure}

## Current Situation
{What is being discussed/reviewed and why}

## Specific Request
{Exactly what Codex should do — review, propose alternatives, identify risks, etc.}

## Constraints
- Be specific and actionable in your feedback
- Categorize issues by severity: critical / warning / suggestion
- If you disagree with the approach, propose a concrete alternative
- Keep responses focused and concise

Execution Flow

User gives instruction
    ↓
Determine mode (Discussion / Review / Mentor)
    ↓
Claude gathers and organizes context
    ↓
┌──────────────────────────────────┐
│  Dialogue loop with Codex        │
│  (follow the mode's protocol)    │
│  Max 3 rounds                    │
└──────────────────────────────────┘
    ↓
Report results to user
(code fixes already applied if any)

Key Rules

• Do not ask the user for intermediate confirmation. Execute autonomously from mode selection through to the final report. When in doubt, take the safer option and keep going.
• Do not blindly trust Codex's output. Claude must always evaluate and judge validity. Codex provides "another perspective"; Claude makes the final call.
• Respect the round limit. Max 3 rounds per mode to prevent infinite loops.
• Keep changes minimal. In Review mode, fix only the flagged issues. No scope creep.
• Maintain transparency. The final report must state what Codex raised, what Claude decided, and why any findings were not adopted.

Report Format

At the end of each mode, report to the user with this structure:

## 🤝 Codex Mentor Report

**Mode:** Discussion / Review / Mentor
**Rounds:** N / 3
**Status:** Consensus / Partial Consensus / Divergent Views

### Summary
{1-2 sentence conclusion}

### Discussion Log
{What was discussed in each round and how the position evolved}

### Final Decision
{Adopted approach or applied fixes}

### Findings Not Adopted
{Codex findings that were rejected, with reasons}

Handling Large Review Scopes

When many files are involved or a full-codebase review is requested:

1. If there are uncommitted changes, scope to the diff only
2. If no diff, select up to 5 files most relevant to the user's instruction
3. Keep each Codex prompt under 3,000 lines
4. If that limit is exceeded, split by file and review sequentially

Reference: Codex CLI Examples

# Single question
codex exec --full-auto -q "Review this TypeScript code for potential issues: $(cat src/index.ts)"

# Review with diff
codex exec --full-auto -q "$(cat <<'EOF'
You are a code reviewer. Review the following diff for bugs, performance issues, and design concerns.
Categorize each finding as critical/warning/suggestion.

$(git diff HEAD~1)
EOF
)"

For long prompts, consider passing via a temp file:

cat > /tmp/codex-prompt.md << 'EOF'
...
EOF
codex exec --full-auto -q "$(cat /tmp/codex-prompt.md)"