Claude Codex Duo: Evidence-Based Review, Debate, and Planning

Three Claude Code plugins that bring Codex into a structured workflow with independent first passes and written evidence.

I’m actively working on claude-codex-duo, an open-source collection of Claude Code plugins for code review, technical debate, and implementation planning with OpenAI Codex.

The project’s defining rule is that agreement between models does not establish whether a claim is correct. Its review workflow requires findings to be checked against evidence, and its debate workflow records the evidence behind each claim.

The repository currently contains three independently installable plugins: codex-pr-review, codex-debate, and codex-deep-plan. Each has a separate command and a defined output. Project overview.

Code review starts with a shared scope

codex-pr-review accepts a pull request, branch, commit comparison, or local uncommitted changes. It pins the review scope and builds a neutral brief before findings exist.

A lead-reviewer agent and Codex receive that brief in separate contexts. Their initial reviews run concurrently. The lead’s findings are sealed, and a join gate checks the required artifacts and hashes before the workflow reads both results together.

The next phase creates a reconciliation ledger. It records findings raised by both reviewers, findings unique to either reviewer, and disagreements. Duplicate findings are combined only when they share the same root cause and location.

Selected findings then enter a bounded consultation. Every P0–P3 finding still requires verification, regardless of its source or whether both models agreed. The verification process calls for evidence such as a reproduction, a traced code path, or relevant test results. A withdrawn claim is checked rather than accepted as settled simply because a reviewer retracted it.

The final report records one merge recommendation under an ordered policy: BLOCK, REQUEST CHANGES, NEEDS CLARIFICATION, APPROVE WITH COMMENTS, or APPROVE. Refuted findings go into a false-positive appendix; unresolved findings remain visible. Review adjudication rules.

For a local review, the documented command shape is:

/codex-pr-review:review-pr local HEAD "Describe the intended change"

Replace the quoted text with the actual intent. Local mode snapshots staged, unstaged, deleted, and non-ignored untracked files through a scratch index outside the repository. It leaves the repository’s own index, refs, stash, reflog, and working files unchanged, while adding unreachable Git objects to represent the snapshot. Local review details.

Technical debate keeps a claim ledger

codex-debate handles a falsifiable motion or a choice between named options. It provides three modes: challenge, compare, and hypothesis.

An illustrative comparison command is:

/codex-debate:debate "Option A: Redis streams vs Option B: Postgres outbox for the job queue" compare 2

This is an invocation example, not a recommendation for either architecture.

Each claim receives an ID, owner, evidence grade, and status. The grades distinguish executed evidence, traced source, cited documents, reasoning, and unsupported assertions. Unsupported assertions cannot decide the ruling.

Replies must maintain a claim with evidence, retract it because of a specific fact, refine it, or commit to a concrete verification step. The protocol also defines stopping conditions and permits an unresolved result. Its final ruling includes the surviving counterargument and recorded concessions. Debate protocol.

Planning separates facts from inferences

codex-deep-plan accepts issue references, PR review comments, individual comment URLs, plain requests, and request files. Its evidence rules distinguish four categories: facts read at a pinned revision, results observed through execution, inferences, and unknowns.

The workflow includes citation checks that resolve source references at the pinned commit and compare quoted text. Decisions require fact or execution evidence; an inference alone is insufficient support.

Codex receives an independent diagnosis brief, followed by a bounded exchange over differences. The requested depth determines the process: a question produces an evidence-backed answer, while a change request produces a plan. Multiple inputs do not automatically become one PR; the workflow checks whether they share a cause or change surface.

For example:

/codex-deep-plan:plan "add rate limiting to the export endpoint" --rounds 1

The example requests a plan. It does not implement rate limiting. The documented handoff places the resulting change plan into Claude Code plan mode when that interface is available. Planning command and evidence rules.

The boundaries matter

The project describes its blind-review separation as procedural, not structural. Codex’s sandbox can read temporary files and Claude Code transcripts. Independence relies on the neutral brief, separate initial contexts, sealed artifacts, and phase ordering; it is not a filesystem isolation guarantee.

The plugins are designed for read-only work on the reviewed checkout. They write evidence artifacts outside the repository, and deep planning can write the plan-mode handoff file. Local review also creates the unreachable Git objects described above.

Using Codex sends repository content to OpenAI. The documented workflow asks whether that is permitted before the first Codex call. If Codex is unavailable, the workflow reports the reduced mode instead of simulating a second model. Boundaries and prerequisites.

Installation and a first run

Prerequisites include Claude Code with plugins enabled, the configured OpenAI Codex plugin, Git, Python 3, and Node. GitHub-based inputs also use gh. The repository documents macOS and Linux support; Windows local review is untested.

Set up the Codex dependency using the repository’s prerequisite instructions, then add the marketplace and install the workflows you need:

claude plugin marketplace add hishamkaram/claude-codex-duo
claude plugin install codex-pr-review@claude-codex-duo --scope user
claude plugin install codex-debate@claude-codex-duo --scope user
claude plugin install codex-deep-plan@claude-codex-duo --scope user

The repository provides the full setup, commands, artifact layouts, troubleshooting guide, and MIT license. Start with a scoped review or a concrete technical question, then inspect the resulting evidence alongside the recommendation.

Originally published on Medium.

Disclosure: This article was drafted with AI using the linked repository documentation.