debate

# debate

Get a second (and third, and fourth) opinion on your implementation plan. The `debate` plugin sends your plan to OpenAI Codex, Google Gemini, and Claude Opus simultaneously, synthesizes their feedback, and has them argue out any disagreements — so you get independent review plus a consensus verdict before writing a line of code.

## Quick Start

```bash
# Install
/plugin marketplace add STRML/cc-plan-debate
/plugin install debate@cc-plan-debate

# Check prerequisites
/debate:setup

# Run a review (while in plan mode, or after describing a plan)
/debate:all
```

Restart Claude Code after installing.

## What it does

```
You: /debate:all

Claude: ✅ codex  ✅ gemini  ✅ opus  — launching parallel review...

  [Codex, Gemini, and Opus review your plan simultaneously]

  ## Codex Review — Round 1        [The Executor]
  The retry logic in Step 4 doesn't handle the case where...
  VERDICT: REVISE

  ## Gemini Review — Round 1       [The Architect]
  Missing error handling when the API is unavailable...
  VERDICT: REVISE

  ## Opus Review — Round 1         [The Skeptic]
  Unstated assumption: this plan assumes the temp directory is writable...
  VERDICT: REVISE

  ## Synthesis
  Unanimous: all reviewers flagged missing error handling
  Unique to Codex: retry logic gap in Step 4
  Unique to Opus: temp directory writability assumption
  Contradictions: none

  ## Final Report
  VERDICT: REVISE — 3 issues to address before implementation

Claude: Revising plan... [updates the plan]
Claude: Sending revised plan back to all reviewers...

  ## Codex Review — Round 2  →  VERDICT: APPROVED ✅
  ## Gemini Review — Round 2  →  VERDICT: APPROVED ✅
  ## Opus Review — Round 2   →  VERDICT: APPROVED ✅

  ## Final Report — Round 2 of 3
  VERDICT: APPROVED — unanimous
```

## Commands

| Command | Description |
|---------|-------------|
| `/debate:setup` | Check prerequisites, verify auth, print allowlist for unattended use |
| `/debate:all` | All available reviewers in parallel + synthesis + debate |
| `/debate:codex-review` | Single-reviewer Codex loop (up to 5 rounds) |
| `/debate:gemini-review` | Single-reviewer Gemini loop (up to 5 rounds) |
| `/debate:opus-review` | Single-reviewer Opus loop (up to 5 rounds) |

## Installation

### From GitHub

```
/plugin marketplace add STRML/cc-plan-debate
/plugin install debate@cc-plan-debate
```

### Local dev

```bash
git clone https://github.com/STRML/cc-plan-debate ~/debate-plugin
/plugin marketplace add ~/debate-plugin
/plugin install debate@debate-dev
```

Restart Claude Code after installing.

## Prerequisites

Run `/debate:setup` to check everything at once. Or manually:

### OpenAI Codex (for `/debate:codex-review` and `/debate:all`)

```bash
npm install -g @openai/codex
export OPENAI_API_KEY=sk-...    # add to ~/.bashrc or ~/.zshrc
```

### Google Gemini (for `/debate:gemini-review` and `/debate:all`)

```bash
npm install -g @google/gemini-cli
gemini auth
```

### Claude Opus (for `/debate:opus-review` and `/debate:all`)

The `claude` CLI is part of Claude Code itself, so it's already installed if you're running this plugin. You also need `jq` to parse its JSON output:

```bash
brew install jq          # macOS
apt install jq           # Linux
```

No API key is required — the `claude` CLI uses Claude Code's stored OAuth credentials automatically.

### GNU timeout — macOS only

macOS doesn't ship `timeout`. Without it the 120s per-reviewer timeout is disabled:

```bash
brew install coreutils
```

## Usage

### `/debate:all [skip-debate]`

Runs all available reviewers in parallel (120s timeout each). If reviewers disagree, Claude sends targeted questions back to each one to resolve contradictions. Iterates up to 3 revision rounds.

```
/debate:all              # full flow with debate
/debate:all skip-debate  # skip debate, go straight to final report
```

### `/debate:codex-review [model]`

Iterative loop with Codex only — good when you want faster turnaround or a focused Codex perspective.

```
/debate:codex-review
/debate:codex-review o4-mini
```

### `/debate:gemini-review [model]`

Same workflow with Gemini.

```
/debate:gemini-review
/debate:gemini-review gemini-2.0-flash
```

### `/debate:opus-review [model]`

Iterative loop with Claude Opus as **The Skeptic** — focused on unstated assumptions, unhappy paths, second-order failures, and security. Uses session resume to maintain context across rounds.

```
/debate:opus-review
/debate:opus-review claude-opus-4-5
```

## Unattended / No-Prompt Use

Each command declares its tool permissions in frontmatter, so Claude Code will ask once per session and remember. To approve permanently across all sessions, run `/debate:setup` to get the exact JSON snippet to add to `~/.claude/settings.json`.

## Troubleshooting

**Gemini produces no output**
Gemini authentication may have expired. Run `gemini auth` to re-authenticate.

**`timeout: command not found`**
Install GNU coreutils: `brew install coreutils` (macOS) or `apt install coreutils` (Linux). Reviews will still work without it, but the 120s timeout won't be enforced.

**Codex session resume fails**
Codex sessions expire after a period of inactivity. The commands automatically fall back to a fresh call and recapture the new session ID.

**Gemini session not found after review**
The session UUID diff uses `gemini --list-sessions` before and after the review call. If sessions shift concurrently (multiple Gemini processes), the diff may be ambiguous and the command falls back to non-resume mode for subsequent rounds.

**Opus exits with "Claude Code cannot be launched inside another Claude Code session"**
This means the nested-session guard wasn't applied. The commands handle this automatically via `unset CLAUDECODE CLAUDE_CODE_ENTRYPOINT` — if you see this error, ensure you're running the latest version of the plugin.

**Opus review requires `jq`**
The `claude` CLI outputs JSON and requires `jq` to extract the review text and session ID. Install with `brew install jq` (macOS) or `apt install jq` (Linux).

**Only one reviewer available**
Single-reviewer commands (`/debate:codex-review`, `/debate:gemini-review`, `/debate:opus-review`) and `/debate:all` all work with any subset of reviewers available. With fewer reviewers, `/debate:all` skips any unavailable reviewer and may skip the debate phase if only one succeeds.

## Security

- Plan content is always passed via **file path or stdin redirect** — never inlined in shell strings
- Dynamic content (revision summaries, AI feedback) is written to temp files and read via `$(cat file)` — never interpolated directly into quoted strings
- Codex runs with `-s read-only` — can read the codebase for context but cannot write files
- Gemini runs with `-s` (sandbox) — cannot execute shell commands
- Gemini runs with `-e ""` — extensions and skills are disabled for each review call
- Opus runs with `--tools ""` — no tool access; `--disable-slash-commands`; `--strict-mcp-config`; hooks disabled — read-only, stateless review

## Custom Reviewers

Add reviewer definitions at `~/.claude/ai-review/reviewers/<name>.md`. These override built-in reviewers with the same `name:` frontmatter value. See `reviewers/codex.md` for the format.

## License

MIT