> ## Documentation Index
> Fetch the complete documentation index at: https://docs.puzld.cc/llms.txt
> Use this file to discover all available pages before exploring further.

# Debate Mode

> Multi-round discussions to explore ideas and trade-offs

Debate mode facilitates structured discussions between AI models, allowing them to present arguments, respond to each other, and refine their positions over multiple rounds.

## Usage

### TUI (Interactive)

```bash theme={null}
/debate <agents> "<topic>"
/settings        # configure rounds & moderator
```

### CLI

```bash theme={null}
puzldai debate "<topic>" -a <agents> [-r rounds] [-m moderator]
```

| Flag | Description |
| - | - |
| `-a` | Comma-separated agents to debate (required) |
| `-r` | Number of debate rounds (default: 2) |
| `-m` | Agent to synthesize the conclusion |

### Examples

```bash theme={null}
# TUI: Debate between Claude and Gemini
/debate claude,gemini "GraphQL vs REST for our API"

# CLI: Three-model debate with 3 rounds and moderator
puzldai debate "Monolith vs microservices" -a claude,gemini,codex -r 3 -m ollama
```

## How It Works

**1. Initial Positions**

Each agent presents their initial position on the topic. All agents respond in parallel.

**2. Response Rounds**

In each subsequent round, agents read all previous responses and can:

* Defend their position with new arguments
* Address counterpoints from other agents
* Update their view if convinced

**3. Conclusion (Optional)**

A moderator agent can synthesize the debate into a balanced conclusion, summarizing agreements and disagreements.

## Configuration

### TUI Settings

Configure debate options via `/settings` → Collaboration tab:

| Setting | Description |
| - | - |
| Rounds | Number of debate rounds (1-5, default: 2) |
| Moderator | Agent to synthesize conclusion (default: none) |

### CLI Flags

```bash theme={null}
# 3 rounds with ollama as moderator
puzldai debate "GraphQL vs REST" -a claude,gemini -r 3 -m ollama
```

## When to Use Debate

Debate mode excels at:

* **Exploring trade-offs** - Different perspectives highlight pros and cons
* **Technical decisions** - Architecture, technology choices, design patterns
* **Edge case discovery** - Adversarial discussion uncovers potential issues
* **Learning** - See how different models reason about problems

## Keyboard Shortcuts

| Key | Action |
| - | - |
| `Escape` | Hide view (keeps running) |
| `Ctrl+E` | Return to debate view |
| `Ctrl+C` | Cancel debate |
| `Enter` | Select winner (after completion) |

## Example Output

```
─── Debate: GraphQL vs REST ───

Round 0 - Initial Positions:

claude: "GraphQL offers significant advantages for our use case..."

gemini: "REST remains the better choice because..."

Round 1 - Responses:

claude: "Addressing Gemini's point about caching..."

gemini: "While Claude makes valid points about flexibility..."

─── Moderator Conclusion ───
Both approaches have merit. For this specific project...
```

## Tips

> [!TIP]
>
> **Choose complementary models** - Different models often have different strengths and perspectives.

> [!TIP]
>
> **2-3 rounds is usually enough** - More rounds can lead to repetition without new insights.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.