> ## 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.

# Consensus Mode

> Collaborative decision-making with proposal and voting

Consensus mode enables multiple AI models to collaborate on a task through a structured process of proposing solutions, voting, and synthesizing the best approach.

## Usage

### TUI (Interactive)

```bash theme={null}
/consensus <agents> "<prompt>"
/settings        # configure rounds & synthesizer
```

### CLI

```bash theme={null}
puzldai consensus "<prompt>" -a <agents> [-r rounds] [-s synthesizer]
```

| Flag | Description |
| - | - |
| `-a` | Comma-separated agents to participate |
| `-r` | Number of voting rounds (default: 2) |
| `-s` | Agent to synthesize final result |

### Examples

```bash theme={null}
# TUI: Three-model consensus
/consensus claude,gemini,codex "Design the authentication system"

# CLI: With 3 rounds and claude as synthesizer
puzldai consensus "Choose the best database" -a claude,gemini,ollama -r 3 -s claude
```

## How It Works

**1. Proposal Phase**

Each agent independently proposes a solution to the task. They receive project structure context but don't see other agents' proposals to avoid bias.

**2. Voting Rounds**

Agents review all proposals and vote for the best one, providing reasoning. Multiple voting rounds allow positions to evolve.

**3. Synthesis**

A synthesizer agent analyzes the votes, identifies the winning proposal, and creates a unified final solution incorporating the best ideas.

## Configuration

### TUI Settings

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

| Setting | Description |
| - | - |
| Rounds | Number of voting rounds (1-5, default: 2) |
| Synthesizer | Agent to synthesize final result (default: auto/first agent) |

### CLI Flags

| Flag | Description |
| - | - |
| `-a` | Comma-separated agents to participate (required) |
| `-r` | Number of voting rounds (default: 2) |
| `-s` | Agent to synthesize final result |

## Actions After Consensus

After consensus completes, you can:

| Action | Description |
| - | - |
| **Build** | Enter Build mode to implement the synthesized solution |
| **Continue** | Accept the result and continue chatting |
| **Reject** | Discard the result |

## Project Context

Consensus mode automatically provides project structure to all agents, enabling them to make informed proposals that reference actual files and directories in your codebase.

## Keyboard Shortcuts

| Key | Action |
| - | - |
| `Escape` | Hide view (keeps running in background) |
| `Ctrl+E` | Return to consensus view |
| `Ctrl+C` | Cancel operation |
| `↑/↓` | Navigate action options |
| `Enter` | Select action |

## Best Practices

> [!TIP]
>
> **Use consensus for architectural decisions** - When there are multiple valid approaches, consensus helps explore options and reach agreement.

> [!WARNING]
>
> **Requires 2+ agents** - Consensus needs at least two models to vote and reach agreement.

## Example Output

```
─── Consensus ───

┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐
│ claude          │  │ gemini          │  │ codex           │
│ [proposal]      │  │ [proposal]      │  │ [proposal]      │
│ Use JWT with... │  │ Session-based...│  │ OAuth 2.0...    │
└─────────────────┘  └─────────────────┘  └─────────────────┘

Voting Round 1...
Winner: claude's proposal (2 votes)

Synthesis:
Based on the consensus, JWT authentication is recommended...
```


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