DEV Community: Hesham Karam

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

Hesham Karam — Sun, 06 Sep 2026 11:37:55 +0000

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.

Claude Code Router: Multiple Model Providers in One Claude Code Session

Hesham Karam — Sun, 06 Sep 2026 11:35:16 +0000

A local Go gateway for explicit model selection, capability checks, and visible routing.

I’m actively working on Claude Code Router, an open-source project that connects Claude Code to first-party Anthropic models and configured external providers through a local gateway.

The command-line tool is called ccr. Claude Code connects to its loopback address, and CCR routes requests to the selected model. Supported provider profiles include OpenRouter, Z.AI, LiteLLM, and trusted local OpenAI-compatible endpoints. The gateway exits when the Claude Code process it launched exits.

This article walks through the project’s documented workflow: configure a provider, register model aliases, switch routes within a session, and inspect what happened. Project overview.

One session, explicit model selection

CCR separates a provider connection from a model alias. The connection defines the endpoint and credential source. The alias names a model route that you can select from Claude Code.

That separation lets a workflow keep using an alias while its configured provider model changes. In a session with preserved Claude authentication, eligible aliases appear alongside permitted Anthropic models in the /model picker. CCR also prints their exact picker IDs at launch.

Switching changes the route used for subsequent work where Claude Code permits it. New subagents and workflows can inherit the active model; existing workers can remain on their original model. Picker entries are generated at launch, so changes to aliases or capability metadata require a relaunch to refresh the visible choices. Routing documentation.

Selecting a registered CCR alias in /model and continuing the conversation. Cropped excerpt; 1.5× playback.

Compatibility is part of the route

CCR tracks provider and model capabilities before forwarding requests. Effective model facts follow a defined order: local overrides, provider discovery, then recognized model hints. Missing metadata remains unknown.

An imported model starts with degraded compatibility status. Importing it does not automatically certify every feature. Other statuses include full, chat-only, and blocked; a chat-only launch disables Claude Code tools, while blocked aliases are refused.

For example, the documented image-input path requires both a translatable image request and an effective capability allowing image input. If those conditions are not met, CCR rejects the request. It does not remove the image or silently send the request to another model.

OpenAI Responses support is also explicit. An OpenAI-compatible endpoint is not automatically treated as a Responses endpoint. The provider and alias must be configured for that route. Managed computer use adds another requirement: an explicitly selected supported executor.

These rules describe compatibility boundaries, not a promise that every provider implements every Claude Code feature. Provider and capability reference.

Getting started

Claude Code must already be installed and available as claude. On macOS, the documented Homebrew installation is:

brew install hishamkaram/tap/claude-code-router
ccr version
ccr doctor

ccr doctor checks the local setup; it is offline by default. Then configure a provider:

ccr init
ccr provider add --interactive
ccr model list

The wizard guides you through the provider profile, connection details, credential source, and model aliases. Providers with discovery expose a searchable model selection flow; other profiles use manual model entry. Nothing is saved until the final review completes.

With working Claude subscription or Anthropic API authentication, launch with:

ccr launch

To start on a configured provider alias, use:

ccr launch --model <alias>

Replace <alias> with a name from your model list. The default authentication mode preserves available Claude authentication. Without Claude authentication, an explicit provider alias allows a provider-only launch; omitting both causes launch to fail visibly. Getting-started guide.

Inspect the route, not the model’s self-description

CCR exposes commands for inspecting configuration, compatibility, and runtime activity:

ccr model show <alias> --json
ccr model test <alias>
ccr conformance run <alias>
ccr status
ccr trace --follow

The live checks contact the configured provider. Runtime records expose the observed alias, provider model, protocol, result, latency, and provider-reported token usage when available. CCR does not estimate monetary cost.

The routing documentation explicitly distinguishes those observations from a model’s generated answer about its own identity. A sentence in a conversation is not the route record. Runtime visibility.

Local state and credentials

CCR uses SQLite for configuration and redacted operational metadata. Its documented credential choices are environment-variable references, permission-restricted key files, and the OS keychain. Raw API keys are not stored in SQLite.

The documented route-history policy excludes prompts, responses, tool arguments, and authorization headers. Configuration exports also exclude credential values, keychain identifiers, and key-file paths; credentials are bound separately on the importing machine. Credential handling and team profiles.

Explore the project

Claude Code Router brings provider configuration, model selection, compatibility checks, and route inspection into one local tool. It is written in Go and released under the MIT license.

The repository includes installation instructions, release notes, and contribution guidelines. If you try a provider route, reproducible compatibility reports are welcome: include the CCR version, model alias, and redacted diagnostic output, without credentials or private prompts.

Originally published on Medium.

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