bl-agent-debater 0.2.0

CLI for orchestrating structured debates between AI agents

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

Command	Description
bl-debater start <name> -p "..." --as <role> --vs <role>	Create debate
bl-debater start ... --context <file-or-url>	Include context (repeatable)
bl-debater respond <name> --as <role> --template	Respond with $EDITOR
bl-debater join <name> --as <role>	Join existing debate
bl-debater wait <name> --as <role>	Wait for your turn
bl-debater watch <name>	Live terminal UI
bl-debater export <name> --format github-comment	Export synthesis
bl-debater status <name>	Check debate status
bl-debater list	List all debates
bl-debater roles	Show available roles

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):

Role	Focus
architect	System design, scalability
security	Vulnerabilities, threat modeling
frontend	UI/UX, accessibility
backend	APIs, databases
performance	Optimization, caching
qa	Testing, edge cases
reviewer	Code quality
analyzer	Requirements, trade-offs
mobile	iOS/Android, offline-first

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

Flag	Default	Description
--agreement	80	Consensus threshold %
--debates-dir	./debates	Debate files directory
--timeout	60	Wait timeout (seconds)
--context	-	Include file or URL content (repeatable)
--format	github-comment	Export format (github-comment, markdown, json)

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