review-council

Review Council

Multi-agent convergence review for Claude Code. Multiple AI models independently review your PR, code, or plan — then discuss until they converge on a curated list of what actually needs changing.

Why

Single-model code review has blind spots. Different models catch different things. Review Council runs multiple reviewers in parallel, compares their findings, and produces a single curated report where:

• Agreed findings (multiple reviewers flagged) = high confidence
• Unique findings (one reviewer) = worth considering
• Conflicts (reviewers disagree) = both perspectives documented

The result: fewer false positives, broader coverage, and a clear priority order.

Quick Start

# Install the plugin
/plugin marketplace add deployhq/review-council
/plugin install review-council

# Check available providers
/review-council:setup

# Review something
/review-council:run              # auto-detect: current PR or staged changes
/review-council:run 42           # review PR #42
/review-council:run src/auth.ts  # review a source file
/review-council:run docs/plan.md # review a plan or document

How It Works

flowchart TD
    A["/review-council:run [target]"] --> B{Detect Target}
    B -->|PR number| C["Fetch PR diff & metadata"]
    B -->|Source path| D["Read source files"]
    B -->|Doc/plan path| E["Read document & references"]
    B -->|No argument| F{Auto-detect}
    F -->|Open PR on branch| C
    F -->|Staged changes| D
    F -->|Unstaged changes| D

    C --> G["Gather Context"]
    D --> G
    E --> G

    G --> H0["Detect Available Providers"]
    H0 --> H["Round 1: Independent Review"]

    H --> I["Claude Subagent"]
    H --> J["Codex (CLI/MCP)"]
    H --> J2["Gemini (CLI/MCP)"]
    H --> J3["Perplexity (API)"]

    I --> K["Synthesize"]
    J --> K
    J2 --> K
    J3 --> K

    K --> K2{Validate outputs}
    K2 -->|"All valid"| L{Disagreements?}
    K2 -->|"Some failed"| K3["Retry (1x max)<br/>or ask user"]
    K3 --> L
    L -->|"Yes"| M["Round 2: Share synthesis, revise"]
    L -->|"No"| N["Final Report"]

    M --> O{Converged?}
    O -->|"Yes"| N
    O -->|"No (max 3 rounds)"| P["Report with dissenting opinions"]

    style A fill:#7c3aed,color:#fff
    style H0 fill:#7c3aed,color:#fff
    style H fill:#2563eb,color:#fff
    style I fill:#6366f1,color:#fff
    style J fill:#059669,color:#fff
    style J2 fill:#059669,color:#fff
    style J3 fill:#059669,color:#fff
    style N fill:#16a34a,color:#fff
    style P fill:#d97706,color:#fff
    style K2 fill:#d97706,color:#fff
    style K3 fill:#d97706,color:#fff

Auto-detection means you usually just run /review-council:run with no arguments. It checks for an open PR on the current branch, then staged changes, then unstaged changes.

Output validation. After Round 1, each reviewer's response is checked for required sections and fields. Malformed responses are retried once; if still failing, the orchestrator asks whether to proceed with the remaining reviewers or abort. Set RC_AUTO_RETRY=true to skip the prompt (useful in CI).

Reviewers

graph LR
    O["Orchestrator<br/>(Claude Code)"] -->|subagent| C["Claude<br/>Reviewer"]
    O -->|"CLI / MCP"| X["Codex<br/>Reviewer"]
    O -->|"CLI / MCP"| G["Gemini<br/>Reviewer"]
    O -->|"API"| P["Perplexity<br/>Reviewer"]

    style O fill:#7c3aed,color:#fff
    style C fill:#6366f1,color:#fff
    style X fill:#059669,color:#fff
    style G fill:#059669,color:#fff
    style P fill:#059669,color:#fff

Reviewer	Transport	Detection
Claude	Native subagent	Always available
Codex (OpenAI)	CLI (codex exec) / MCP fallback	which codex or MCP tool
Gemini (Google)	CLI (gemini) / MCP fallback	which gemini or MCP tool
Perplexity	Sonar API (curl)	PERPLEXITY_API_KEY env var

Minimum 2 reviewers needed for convergence mode. With only Claude, runs in single-reviewer mode. Providers are auto-detected at runtime — no manual configuration needed.

Setup

Prerequisites

• Claude Code CLI
• GitHub CLI (gh) — for PR reviews (optional)
• At least one additional reviewer for convergence mode:
  • Codex CLI — npm install -g @openai/codex && codex login
  • Gemini CLI — npm install -g @google/gemini-cli
  • Perplexity API key — set PERPLEXITY_API_KEY env var

Install

/plugin marketplace add deployhq/review-council
/plugin install review-council

Providers are auto-detected at runtime. Run /review-council:setup to check which providers are available.

Configuration

Optional environment variables for tuning behavior: