ai-debate

AI Debate — Claude Code Plugin

A structured debate between AI agents, packaged as a Claude Code plugin. Install once, then use /debate from any directory to run a fully orchestrated debate on any topic.

Specialised agents — Chair, N configurable Debaters, Reporter, Verifier, Audience, and Assessor — argue a topic, fact-check each other's sources in real time, and produce a publishable written record.

---

How It Works

Agent	Role
Chair	Neutral moderator. Manages turn order, issues rulings, declares the outcome. Proposes the debater lineup and waits for user approval before spawning agents.
Debaters	N configurable participants, each with their own persona, starting position, and incentives — proposed by the Chair at startup and approved by the user before the debate begins.
Reporter	Silent observer. Produces the transcript, summary, and blog post at the end.
Verifier	Async fact-checker. Verifies every cited URL and flags fabricated sources.
Audience	Engaged observer. Submits clarifying questions mid-debate; gives a final opinion at close.
Assessor	Post-debate reviewer. Evaluates each agent's performance and produces an improvement report.

The Chair is the lead Claude Code session. It proposes a debater lineup based on your topic, waits for your approval, then spawns all agents as teammates and coordinates a structured debate through opening statements, multiple rebuttal rounds, and closing statements before declaring a winner.

All debate entries are written to {output_dir}/debate-log.jsonl — an append-only log inside the run's output directory that acts as the shared source of truth for all agents.

---

Prerequisites

• Claude Code installed and authenticated
• Agent Teams experimental feature enabled (set the env var below)
• bash, python3, and flock available (standard on macOS and Linux)

---

Installation

Via marketplace (recommended):

/plugin marketplace add colings86/ai-debate
/plugin install ai-debate@ai-debate

Directly from a local clone:

claude plugin install ./plugins/ai-debate

After installation, the /debate skill is available in any Claude Code session.

---

Quick Start

In any Claude Code session (no need to cd into the repo):

CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 claude

Then type:

/debate

The Chair will ask for your topic if you haven't provided one, propose a debater lineup, and wait for your approval before starting.

Or provide a topic immediately:

/debate The topic is: Should artificial intelligence be used to make judicial decisions?

---

Specifying Debaters

You have three ways to tell the Chair who should debate:

Option 1 — No spec (Chair decides):

/debate The topic is: X.

The Chair proposes a contextually appropriate lineup — typically 2 debaters in classic adversarial format, or 3 if the topic has distinct natural perspectives. You review and approve before the debate begins.

Option 2 — Persona hints:

/debate Topic: X. I want a venture capitalist, a labour economist, and an AI safety researcher.

The Chair fleshes out each persona with an appropriate starting position and incentives, then presents the lineup for your approval.

Option 3 — Specific detail:

/debate Topic: X.
Debater 1: venture-capitalist — argues AI is net positive for employment; incentivised by growth narratives.
Debater 2: labour-economist — argues structural unemployment is underappreciated; incentivised by worker welfare data.

The Chair uses your specifications directly, filling in any gaps you leave.

Modifying the proposed lineup: After the Chair presents its proposal, you can reply "Can you make the second debater more sceptical, focused on data quality issues?" and the Chair will revise and re-present before proceeding.

Debater name constraint: Names must be alphanumeric plus hyphens only (e.g., venture-capitalist, labour-economist). The Chair handles this automatically.

---

Watching the Debate

The Chair narrates progress in its main session. If you have tmux available, you can split each agent into its own pane for full visibility:

tmux new-session -s debate
export CLAUDE_CODE_SPAWN_BACKEND=tmux
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 claude

You can also tail the debate log in another terminal (substitute your run's output directory):

tail -f output/<timestamp>-<slug>/debate-log.jsonl | python3 -c "
import sys, json
for line in sys.stdin:
    e = json.loads(line)
    print(f'[{e[\"seq\"]}] {e[\"speaker\"]}: {e[\"type\"]} — {e[\"content\"][:80]}')
"

---

Reading the Output

When the debate concludes, the Reporter writes all output files to a timestamped directory under output/ in your current working directory. For example: