Agent Council

A multi-agent deliberation system where diverse AI coding agents collaborate through structured rounds to solve problems better than any single agent could alone.

Inspired by Andrej Karpathy's LLM council idea, but extended to full coding agents — each with their own tools, MCP servers, and knowledge bases.

Why Agent Councils?

This is not just multiple LLM API calls. Each agent (Claude Code, Gemini, Codex, OpenCode) is a complete coding agent with:

• Its own tool ecosystem
• File access and code exploration
• Web search and knowledge bases
• Different training data and reasoning patterns

The value comes from genuinely different systems analyzing the same problem, not multiple prompts to the same model.

How It Works

Round 1: Initial     → Each agent independently proposes a solution
Round 2: Critique    → Agents read others' proposals and identify weaknesses
Round 3: Defense     → Agents defend or revise based on critiques
Round 4: Synthesis   → Chairman consolidates into final recommendation

Coordination happens through files — no server, no infrastructure. Agents read markdown, write markdown, and the deliberation unfolds asynchronously.

Setup

Prerequisites:

• Python 3.10+
• tmux (for interactive mode only)
• At least 2 coding agents installed (e.g., Claude Code, Gemini CLI, Codex, OpenCode)

Install:

git clone https://github.com/quasilabs/agent-council.git
cd agent-council

No dependencies to install — pure Python, no third-party packages.

Your First Council

Step 1: Create a council

python3 agent_council.py new my-first-council
cd my-first-council

This creates a self-contained session:

my-first-council/
├── COUNCIL.md                  # Council rules and member perspectives
├── PROBLEM.md                  # Where you define the problem
├── ROUND-STATUS.md             # Track progress
├── council_core.py             # Shared module
├── watch_council.py            # Auto-advance rounds (tmux mode)
├── run_headless_council.py     # Run without tmux
├── headless-commands.json      # Agent CLI command config
├── start-council.sh            # Launches all agents in tmux
├── prompts/                    # Ready-to-use prompts for each round
│   ├── claude-round-1.md
│   ├── gemini-round-1.md
│   └── ...
├── workspace/                  # Shared context (add files here)
└── rounds/                     # Where agents write their reports
    ├── 1-initial/
    ├── 2-critique/
    ├── 3-defense/
    └── synthesis/

Step 2: Define the problem

Edit PROBLEM.md with your question or challenge:

# Problem Statement

We need to design an authentication system for our API.

## Context
- REST API serving mobile and web clients
- Currently no auth, moving to production
- Team has experience with JWT but open to alternatives

## Constraints
- Must support token refresh
- Need to revoke access for specific users
- Budget for managed services if justified

## What We Need
A concrete recommendation with tradeoffs explained.

Step 3: (Optional) Customize member perspectives

Edit COUNCIL.md to adjust agent perspectives. Defaults:

- **claude**: Systems Thinker and Inventor with long term perspective
- **gemini**: Pragmatic Architect focused on scalability and stability
- **codex**: Devil's advocate, critical thinker, challenges assumptions
- **opencode**: Obsessed with maintainability, testability, correctness

Step 4: Add context (optional)

Drop any relevant files into workspace/ — code samples, research notes, existing docs. Agents will explore this folder.

Step 5: Run the council

You have two modes: interactive (tmux, manual or auto-advance) and headless (fully automated).

Option A: Interactive (tmux)

# Launch all agents in tmux panes
./start-council.sh

# In a separate terminal, auto-advance rounds:
python3 watch_council.py --start

The watcher monitors report files, updates ROUND-STATUS.md, and automatically sends the next round's prompts to each agent's tmux pane when all reports are complete.

You can stop it any time with Ctrl+C. To run a single check without looping:

python3 watch_council.py --once

Option B: Headless (no tmux)

# Run all rounds automatically
python3 run_headless_council.py

# Or run one round at a time
python3 run_headless_council.py --auto=false
python3 run_headless_council.py --auto=false --do-next-round

The headless runner invokes each agent's CLI directly, captures output, and writes reports to rounds/. It validates that all agent binaries are on PATH before starting and has a configurable per-agent timeout (default: 600s).

Edit headless-commands.json to customize agent CLI commands.

Step 6: Read the result

Open rounds/synthesis/synthesis.md for:

• Areas of agreement
• Areas of disagreement (and why)
• Recommended path forward
• Minority opinions worth noting

Tips

Choosing problems: Councils work best for architectural decisions, design tradeoffs, and complex problems with multiple valid approaches. Don't use them for simple bugs or clear-cut tasks.

Agent diversity: The value is in different perspectives. If you only have Claude, you can still run a council with different Claude instances given different personas — but true diversity (different models, different tools) yields better results.

Reading the deliberation: The synthesis is the summary, but the real insight is often in the critique and defense rounds. Read those to understand why the council reached its conclusions.

Acknowledgments

The panel-based persona system (7-section agent profiles with polarity pairs, grounding protocols, and cross-referenced blind spots) was inspired by 0xNyk/council-of-high-intelligence — 18 beautifully crafted AI personas for multi-perspective deliberation.

License

MIT