review-by-opp:help

review-by-opp Help

You are answering questions about the review-by-opp Claude Code plugin.

What is review-by-opp?

A Claude Code plugin that pairs Claude (builder) with OpenAI Codex CLI (independent auditor). It keeps a strict issue ledger so Claude cannot claim "all fixed" until every Codex review finding is actually closed.

Why does this exist?

AI coding agents (Claude, Codex, etc.) have a problem: they mark their own homework. When Claude says "all issues fixed", there's no independent verification. You're trusting the builder to also be the auditor.

review-by-opp fixes this by enforcing separation of concerns:

• Claude builds - writes code, fixes bugs, implements features
• Codex audits - independently reviews Claude's work, finds issues Claude missed
• The ledger enforces - a deterministic stop gate prevents Claude from claiming completion until every finding is actually resolved

This creates an adversarial review loop where two different AI models hold each other accountable, with a mechanical gate that can't be talked past.

• No API keys required - uses signed-in Codex account (npx @openai/codex login)
• Local-first - all data stays on disk in reviews/current.json
• Deterministic stop gate - a shell hook blocks Claude from stopping if blocking findings remain

Available Commands

Command	What it does
/review-by-opp:start	Initialize a new review session. Checks git, Codex, and config.
/review-by-opp:review	Run Codex audit on your code. Parses findings into the ledger.
/review-by-opp:fix	Address findings one by one. Each fix requires an explicit resolution.
/review-by-opp:status	Show session status - open findings, rounds, agent config.
/review-by-opp:resume	Resume an existing session from reviews/current.json.
/review-by-opp:finalize	Run exit gate. Blocks if findings remain. Emits final verdict.
/review-by-opp:help	This help page.

Typical Workflow

1. /start - initialize session
2. /review - Codex audits your code, findings appear in the ledger
3. /fix - Claude fixes issues, marks each with a resolution state
4. /review - re-audit to verify fixes (repeat until clean)
5. /finalize - exit gate checks all findings are resolved

Configuration

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

{
  "reviewLedger": {
    "maxRounds": 4,
    "reviewScope": "diff",
    "blockingSeverities": ["critical", "high", "medium"]
  },
  "codex": {
    "modelStrategy": "best_available",
    "model": "",
    "reasoningEffort": "",
    "auditMode": "standard",
    "deepAuditReasoningEffort": "xhigh"
  }
}

Prerequisites

1. Codex CLI signed in: npx @openai/codex login (one-time, uses ChatGPT account)
2. Plugin loaded: /plugins → Add from local path, or claude --plugin-dir /path/to/review-by-opp

Resolution States

Each finding must be resolved with one of: fixed, wont_fix, false_positive, accepted_risk, deferred, duplicate.

• fixed requires a resolution_note explaining the fix
• The exit gate blocks if any blocking finding is still open or fixed without a note

Answer the user's question about review-by-opp based on this information. If they ask something not covered here, check the project's docs/ directory for more details.