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

Model and reasoning control

• Claude model and effort are always user-controlled through Claude Code's own UI and config. This plugin does not override your Claude settings.
• Codex defaults to inherited user config (model/profile/reasoning) and is fully configurable. Deep audits can opt into xhigh.
• The plugin does not hardcode both agents aggressively - it enforces review completeness, not agent settings.

How it differs from a generic review loop

Resolution states

Every finding ends in exactly one state:

Final verdicts

Local data model

All state is stored locally in reviews/:

reviews/
  current.json       # Active session state
  rounds/
    round-1.json     # Round snapshots
    round-2.json
  summaries/
    summary-1.json   # Round summaries
    summary-2.json
  artifacts/
    round-1-*.txt    # Raw command/check artifacts

All files are JSON, easy to inspect and diff.

Troubleshooting

Security and privacy

• Local-first. All data stays in your repo's reviews/ directory.
• No cloud backend. No data is transmitted anywhere except through Claude and Codex, which the user explicitly invokes.
• No API keys required. Users bring their own signed-in Claude and Codex accounts.
• No UI scraping. The plugin uses Codex CLI's documented non-interactive exec command.
• Trust model: You trust Claude (Anthropic) and Codex (OpenAI) as much as you already do by having them installed and signed in. This plugin adds no new trust requirements.

Contributing

See CONTRIBUTING.md.