agent-debate

# agent-debate

<p align="center">
  <img src="assets/banner.png" alt="agent-debate banner" width="700">
</p>

AI agents debate your technical decisions — then you make the call.

Two to four agents (Gemini, Codex, Gemini, Gemini) edit a shared markdown file in-place. They strikethrough to disagree, cite `file:line` as evidence, track disputes in a log, and must converge or escalate. It's adversarial code review, not a chatbot.

## What a debate looks like

Here's a real excerpt from a [3-agent debate on adding OpenRouter support](debates/1-2026-03-07-add-openrouter-support.md) (Gemini vs Codex vs Gemini):

```markdown
~~Why a wrapper: Dependencies are just `curl` + `jq`, both standard
on macOS/Linux. [A1-R1]~~
Wrapper is correct, but `jq` is unnecessary dependency surface for v1.
Evidence: repo currently has no `jq` dependency, while `python3` is already
required by orchestrator (`orchestrate.sh:139,445,492,753`). Minimum viable
should be a Python wrapper using stdlib `json` + `urllib.request`. [A2-R1]

### Gemini accepts Codex's corrections [A1-R2]

**Python wrapper over bash+jq:** Codex is right. Verified: `orchestrate.sh`
already requires `python3` at 4+ callsites. Adding `jq` as a new dependency
when Python stdlib can do the same job is unnecessary. Conceding. [A1-R2]
```

Agents propose, disagree with evidence, and concede when wrong. Every claim is grounded in actual code. The [full debate](debates/1-2026-03-07-add-openrouter-support.md) converged in 1 round with all disputes closed.

## Why not just ask one AI?

- **One agent has blind spots.** A second agent catches what the first missed — wrong assumptions, unnecessary dependencies, missing code paths.
- **Evidence, not vibes.** The protocol forces agents to cite `file:line`, paste log output, and verify each other's claims before agreeing.
- **Scope creep dies here.** Agents must justify every addition. "Easy to add" is not a reason. Unrelated ideas go to a parking lot.
- **You decide, they inform.** Age