This repository provides workflows and a Claude Code skill for using OpenAI Codex CLI as an independent verification AI alongside your primary AI agent. The pattern treats Codex not as a replacement but as a peer — a second model with different training, different reasoning, and different blind spots — that you consult at key decision points: before committing, when evaluating competing approaches, or when you want implementation delegated to an isolated environment.
- Different models have different reasoning strengths and blind spots. What one model overlooks, another often catches.
- Independent review finds issues that single-model workflows miss — especially in security and logic, where model-specific reasoning patterns create systematic gaps.
- Style disagreements between models are noise, not signal. Two models trained differently will have different formatting preferences. Filter those out; only bugs, security vulnerabilities, and logic errors matter.
- Two perspectives structured into a clear format — with explicit divergence analysis — give you better information than asking one model to review its own work.
Human (domain knowledge, final decisions)
↕
Primary AI (orchestrator, deep codebase understanding)
↕
Codex CLI (independent verification, second opinion)
The human stays in control. The primary AI orchestrates and understands context. Codex CLI provides an independent signal. Nothing gets applied automatically — every finding goes through the human.
- OpenAI Codex CLI installed:
npm install -g @openai/codex
- OpenAI API key configured (
codex authorOPENAI_API_KEYenv var) - Git repository (for implement mode and review mode)
- Optional: Claude Code (for plug-and-play skill integration)
For Claude Code users (one-liner):
git clone https://github.com/Real-AI-Engineering/codex-partner.git ~/.claude/skills/codex-partner && ln -s ~/.claude/skills/codex-partner/skills/codex-partner ~/.claude/skills/codex-partner-skillVerify: restart Claude Code, then type /codex — the skill should activate and ask which mode you want (review, ask, or implement).
Update:
cd ~/.claude/skills/codex-partner && git pullUninstall:
rm ~/.claude/skills/codex-partner-skill && rm -rf ~/.claude/skills/codex-partnerFor standalone use: no install needed — read the docs/ directory for workflow documentation you can adapt to any AI assistant.
| Mode | Purpose | Command |
|---|---|---|
| Review | Independent code review of current changes | /codex review |
| Ask | Get second opinion for debate | /codex ask "question" |
| Implement | Delegate implementation to isolated worktree | /codex implement "spec" |
Detailed documentation:
Seven guardrails that make this pattern safe and useful:
- Never auto-apply Codex findings. Always present to user first.
- Filter style disagreements. Different models have different aesthetics — only flag bugs, logic errors, security, and performance.
- Max 2 Codex calls per invocation. Each call has ~8K+ token overhead. If more are needed, invoke
/codexagain as a fresh call. - Cost awareness. Mention token cost if the task is trivial for Codex — not every question warrants a full model call.
- Error handling. Report Codex CLI failures clearly (auth expired, network error, timeout) and suggest next steps.
- Worktree cleanup. Always clean up after implement mode — on success, failure, or discard. Never leave orphaned worktrees.
- No Codex for Codex. Do not use Codex to review Codex output. One round only.
Other Real-AI-Engineering projects:
- sigil — risk-adaptive development pipeline with adversarial code review
- herald — daily curated news digest plugin for Claude Code
- teams-field-guide — comprehensive guide to Claude Code multi-agent teams
- proofpack — proof-carrying CI gate for AI agent changes
- OpenAI Codex CLI — Official CLI repository
- Codex CLI Documentation — OpenAI platform docs
- Multi-model verification patterns — Agent Teams field guide with orchestration patterns
See CONTRIBUTING.md.
MIT — see LICENSE.