Codex Peer Review
Consult OpenAI's Codex CLI for peer review before presenting significant decisions or completed work to user.
When to Auto-Trigger (Without Explicit /codex)
Auto-consult Codex when about to:
- Present 2+ alternative approaches to solve a problem
- Complete a significant feature implementation
- Propose architectural decisions
- Suggest refactoring strategies
- Present trade-off analysis
Skip auto-consultation for:
- Trivial fixes (typos, formatting, simple one-liners)
- Direct user instructions with no ambiguity
- Information lookups / explanations
- When user explicitly said "just do X"
Codex CLI Reference
Code Review (Scoped)
# Review uncommitted changes (staged + unstaged + untracked)
codex exec review --uncommitted "Focus on: <specific concerns>"
# Review against base branch
codex exec review --base main "Focus on: <specific concerns>"
# Review specific commit
codex exec review --commit <SHA> "Focus on: <specific concerns>"
Freeform Consultation
# Tech decisions, architecture questions, approach validation
codex exec "Given context X, should we use approach A or B? Consider: <factors>"
Prompt Crafting
Claude decides how to prompt Codex. Guidelines:
- Be specific about what feedback you want
- Provide relevant context (file names, constraints, goals)
- For code review: mention what changed and why
- For decisions: frame the trade-offs clearly
Review Loop Protocol
Max Iterations: 3
Execute up to 3 rounds of Claude ↔ Codex exchange:
-
Round 1: Initial consultation
- Send context + question/code to Codex
- Receive Codex's feedback
-
Round 2 (if disagreement): Counter-argument
- If Claude disagrees with Codex's assessment, argue back
- Provide reasoning for disagreement
- Ask Codex to reconsider or clarify
-
Round 3 (if still unresolved): Final exchange
- Last attempt at consensus
- If still disagreeing, note the impasse
Disagreement Handling
Do NOT blindly accept Codex feedback. Evaluate critically:
- Does the suggestion align with project conventions?
- Is the concern valid given the specific context?
- Would the change actually improve the code/decision?
If Claude disagrees:
codex exec "You suggested X, but I disagree because Y. The context you may have missed: Z. Please reconsider or explain why X is still better."
Iteration Limit Reached
If 3 rounds pass without consensus, notify user:
⚠️ Codex review: Reached iteration limit without consensus
**Point of contention**: [what we disagreed on]
**Claude's position**: [your stance + reasoning]
**Codex's position**: [their stance + reasoning]
Proceeding with: [which approach and why]
Output Format
After consultation completes, summarize for user:
## Codex Review Summary
**Consulted on**: [code changes | tech decision | architecture]
**Consensus reached**: Yes/No (N rounds)
### Key Points
- [Agreement 1]
- [Agreement 2]
### Disagreements (if any)
| Topic | Claude | Codex | Resolution |
|-------|--------|-------|------------|
| ... | ... | ... | ... |
### Final Decision
[What was decided and brief rationale]
Invocation Modes
Explicit: /codex or /codex-review
User explicitly requests peer review. Always execute full loop.
Auto-trigger
When about to present alternatives or complete significant work:
- Pause before responding to user
- Run Codex consultation
- Incorporate feedback (or note disagreement)
- Then present to user with review summary
Examples
Code Review (Uncommitted Changes)
codex exec review --uncommitted "Review this authentication refactor. Key changes: moved from session-based to JWT. Check for security issues and edge cases."
Architecture Decision
codex exec "Building a real-time notification system. Options: A) WebSockets with Redis pub/sub, B) Server-Sent Events with PostgreSQL NOTIFY, C) Polling with caching. Constraints: <1000 concurrent users, existing PostgreSQL infra, team familiar with Redis. Which approach and why?"
Validating Trade-offs
codex exec "User asked for feature X. I'm proposing to implement it via Y because of Z. Are there approaches I'm missing? Any concerns with Y?"