bl-agent-debater

┌────────────────────────────────────────────────────────────────────────┐
│                                                                        │
│  ██████╗ ██╗      ██████╗ ███████╗██████╗  █████╗ ████████╗███████╗   │
│  ██╔══██╗██║      ██╔══██╗██╔════╝██╔══██╗██╔══██╗╚══██╔══╝██╔════╝   │
│  ██████╔╝██║█████╗██║  ██║█████╗  ██████╔╝███████║   ██║   █████╗     │
│  ██╔══██╗██║╚════╝██║  ██║██╔══╝  ██╔══██╗██╔══██║   ██║   ██╔══╝     │
│  ██████╔╝███████╗ ██████╔╝███████╗██████╔╝██║  ██║   ██║   ███████╗   │
│  ╚═════╝ ╚══════╝ ╚═════╝ ╚══════╝╚═════╝ ╚═╝  ╚═╝   ╚═╝   ╚══════╝   │
│                                                                        │
│  Structured debates between AI agents                                  │
│                                                                        │
└────────────────────────────────────────────────────────────────────────┘

One AI gives one perspective. Two AIs surface counterarguments, trade-offs, and keep each other honest.

When to use what:

• Claude-only debates? Use claude-code-cookbook directly — it has richer capabilities with subagents and built-in roles.
• Multi-agent debates? Use bl-debater — it bridges different AI systems (Claude + Codex, Claude + GPT, etc.) via a file-based protocol.

Note: Commands are executed by AI agents inside their CLI environments (Claude Code, Codex, or any LLM client with filesystem access). You ask your AI to run the commands — it handles the debate.

Demo

Example: debates/auth.md

# Debate: auth

**Participants:** architect vs security
**Consensus:** 80%

---

## Round 1 - Architect

### Position
- JWTs are stateless, scale horizontally without session storage

### Key Points
- No database lookup per request
- Easy to distribute across microservices

### Proposal
- Use JWTs with 24-hour expiry

**Agreement: 0%**

[WAITING_SECURITY]

---

## Round 1 - Security

### Strengths
- Agree JWTs scale better horizontally

### Concerns
- JWTs can't be revoked without a blocklist
- 24-hour expiry is too long if credentials leak

### Proposal
- Short-lived access tokens (15 min) + server-side refresh tokens

**Agreement: 60%**

[WAITING_ARCHITECT]

---

## Round 2 - Architect

### Strengths
- Valid point on revocation — refresh tokens solve this

### Concerns
- None remaining

### Proposal
- Accept: 15-min JWTs + server-side refresh tokens

**Agreement: 85%**

[PROPOSE_FINAL]

## Final Synthesis

Short-lived JWTs (15 min) for stateless auth, with server-side
refresh tokens for revocation. Best of both approaches.

[CONFIRM?]

---

## Round 2 - Security

Confirmed.

[CONFIRMED]
[DEBATE_COMPLETE]

Installation

pip install bl-agent-debater

Or install from source:

git clone https://github.com/beyond-logic-labs/bl-agent-debater.git
cd bl-agent-debater
pip install -e .

Commands

Debates Directory

--debates-dir is a global option and must come before the subcommand:

bl-debater --debates-dir /path/to/debates join auth --as architect

Tip: run bl-debater status <name> first to confirm participants and whose turn it is.

Context Injection

Include file content or URLs directly in the problem statement:

bl-debater start pr-review -p "Review this PR" \
  --as claude --vs codex \
  --context docs/adr/0004.md \
  --context https://github.com/org/repo/pull/7.diff

Editor Integration

Use your $EDITOR to write responses with pre-filled templates:

bl-debater respond auth --as architect --template

The template includes the correct round header, sections, and validation on save.

Export Synthesis

Export completed debate synthesis for use elsewhere:

bl-debater export auth --format github-comment   # For PR comments
bl-debater export auth --format json             # For automation
bl-debater export auth --format markdown -o REVIEW.md

Roles

Built-in roles (Markdown and YAML formats supported):

Custom Roles (YAML)

Create custom roles with rich metadata:

# roles/security-reviewer.yaml
name: security-reviewer
description: OWASP-focused security specialist

expertise:
  - OWASP Top 10
  - Authentication/Authorization
  - Secrets management

evaluation_criteria:
  - Does the code handle untrusted input safely?
  - Are secrets properly managed?

style: Direct and thorough
consensus_weight: 1.0

Role lookup paths (in priority order):

1. ./roles/ — Project-specific roles
2. ~/.bl-debater/roles/ — User global roles
3. Package bundled roles

Options

Protocol

1. Debates stored in debates/<name>.md
2. Each response ends with [WAITING_<ROLE>]
3. wait command polls until marker matches your role
4. At consensus: [PROPOSE_FINAL] → [CONFIRM?] + [WAITING_<ROLE>] → [CONFIRMED] → [DEBATE_COMPLETE]
5. Timeouts: [TIMEOUT] ends abandoned debates

Live Watch Mode

Watch debates unfold in real-time from a third terminal:

bl-debater watch auth
bl-debater watch auth --plain  # Simple single-line output

Features:

• Color-coded roles — Each participant gets a distinct color
• Progress bar — Visual consensus tracking toward threshold
• Live updates — Auto-refreshes as agents write responses
• Animated spinner — Shows which role is being waited on
• Statistics — Duration, word count, round tracking
• Environment-aware — Automatic plain output for CI/non-TTY

▶ BL-DEBATER LIVE  │  auth.md
──────────────────────────────────────────
● ARCHITECT  vs  ● SECURITY  │  Round 2
Consensus: [████████████░░░░░░░░] 60% → 80%
──────────────────────────────────────────

╭─ Round 2 • ARCHITECT ───────────────────╮
│ Strengths                               │
│   • Valid point on revocation           │
│                                         │
│ Concerns                                │
│   • None remaining                      │
│                                         │
│ Agreement: 85%                          │
╰─────────────────────────────────────────╯

⠹ Waiting for SECURITY...
Watching: 2m 15s │ Ctrl+C to exit

Plain mode (auto-enabled in CI, non-TTY, or with NO_COLOR):

[auth] Round 2 | Waiting: SECURITY | Agreement: 60% -> 80% | 12:34:56

Documentation

• docs/AGENT_GUIDE.md — Instructions for AI agents
• CONTRIBUTING.md — How to contribute

Limitations

• Single machine only (file-based)
• 2-second polling interval
• Manual command invocation required
• No conflict resolution for simultaneous writes

Status

Experimental — Working prototype exploring multi-agent debate patterns.

The vision: evolve into something like claude-code-cookbook but for multi-agent collaboration. Ready-to-use debate templates, role libraries, consensus strategies.

Credits

• Role prompts adapted from claude-code-cookbook by wasabeef

License

MIT