review-by-opp

review-by-opp

A Claude Code plugin that uses your signed-in Codex account as an independent reviewer and keeps a strict issue ledger, so Claude cannot claim "all fixed" until every review finding is actually closed.

---

Why this exists

I use Claude Code for heavy coding and Codex CLI to review the output. In my experience, Claude Code is better at building and Codex is better at catching issues. Using both together has worked really well for me.

But the workflow was painful. Copy-paste findings from Codex into Claude. Watch Claude fix some of them and claim "all done" when half are still open. Manually track what was actually resolved. Repeat. I got fed up.

So I built review-by-opp. It automates the Claude + Codex review loop and enforces item-by-item closure tracking with a stop gate that blocks completion while findings remain unresolved. Codex audits. The plugin prevents fake completion.

How it works

flowchart TD
  A["Claude builds changes"] --> B["Run review"]
  B --> C["Codex exec --sandbox read-only"]
  C --> D["Findings saved to reviews/current.json"]
  D --> E{"Blocking findings open?"}
  E -- Yes --> F["Fix findings"]
  F --> B
  E -- No --> G["Finalize"]
  G --> H["Stop gate checks session state"]
  H --> I["Final verdict"]

Key principle: Claude builds. Codex audits. The plugin prevents fake completion.

Quick start

Prerequisites

• Claude Code installed and signed in
• Codex CLI installed and signed in
• A git repository
• macOS, Linux, or WSL

Install

# Sign into Codex first (one-time, uses your ChatGPT account, no API key needed)
npx @openai/codex login

# Option 1: Add plugin in Claude Code chat
/plugins  # then "Add from local path" or "Add marketplace"

# Option 2: Clone and load
git clone https://github.com/akshan-main/review-by-opp.git
claude --plugin-dir ./review-by-opp

# Option 3: Development / test
cd review-by-opp
npm install && npm run build
claude --plugin-dir .

Usage

All commands are typed in Claude Code's chat (VS Code panel or CLI). No API keys required for either agent.

/review-by-opp:start       Start a guarded implementation + review session
/review-by-opp:review      Run Codex review against current diff
/review-by-opp:fix         Address findings one by one
/review-by-opp:status      Show round count, findings, and exit gate status
/review-by-opp:resume      Resume an existing session
/review-by-opp:finalize    Close the session (blocked if findings remain)
/review-by-opp:help        Learn about the plugin and available commands

Demo walkthrough

In Claude Code chat (VS Code or CLI):

> /review-by-opp:start

# Write your code as usual with Claude
> Implement the user authentication module

# When ready, run the Codex review
> /review-by-opp:review

# Claude receives structured findings - fix them
> /review-by-opp:fix

# Check progress
> /review-by-opp:status

# Repeat review/fix until clean
> /review-by-opp:review
> /review-by-opp:fix

# Finalize when all findings are resolved
> /review-by-opp:finalize

Configuration

Create .review-by-opp.json in your project root:

{
  "reviewLedger": {
    "maxRounds": 4,
    "reviewScope": "full-repo",
    "blockingSeverities": ["critical", "high", "medium"],
    "rerunChecks": true,
    "allowedUnresolvedCategories": [],
    "stalledThreshold": 2,
    "debug": false
  },
  "codex": {
    "role": "auditor_only",
    "modelStrategy": "best_available",
    "model": "",
    "reasoningEffort": "",
    "deepAuditReasoningEffort": "xhigh",
    "auditMode": "standard",
    "commandOverride": ""
  },
  "claude": {
    "role": "builder",
    "modelControl": "user_managed",
    "effortControl": "user_managed"
  }
}

Key config fields

Field	Default	Description
maxRounds	4	Maximum review rounds before forced stop
reviewScope	"full-repo"	What to review: full-repo, diff, changed-files, changed-files-plus-tests
blockingSeverities	["critical","high","medium"]	Severities that block finalization
codex.modelStrategy	"best_available"	best_available, fixed, inherit_if_possible
codex.reasoningEffort	"" (inherit)	Optional Codex reasoning effort override for standard audits
codex.deepAuditReasoningEffort	"xhigh"	Reasoning effort for deep audit mode
claude.modelControl	"user_managed"	Claude model is always user-controlled

Model and reasoning control