---
name: council
description: >
  Multi-model structured deliberation across AI providers. Convenes 2-5 models
  to independently analyze a question, cross-pollinate perspectives with
  convergence protocols (ADOPT/MERGE/DEFEND/CHALLENGE), and synthesize a
  recommendation with confidence scores and preserved dissent. Use when facing
  architecture decisions, design tradeoffs, debugging dead ends, security reviews,
  or any question where one model's bias could mislead.
compatibility: Requires Python 3.10+ and an OpenRouter API key (OPENROUTER_API_KEY)
license: MIT
metadata:
  author: moiz
  version: "1.0.0"
---

# Council of Claude

Multi-model deliberation for critical decisions.

## When to Use

The council is your cognitive diversity engine. Invoke it when:

- **Architecture decisions**: Database choice, service boundaries, caching strategy
- **Design tradeoffs**: Performance vs complexity, flexibility vs simplicity
- **Debugging dead ends**: You've tried 3 approaches and they all fail differently
- **Security reviews**: Threat modeling, auth design, data flow analysis
- **Strategic choices**: Product direction, technical debt prioritization
- **Any decision where a single model's bias could mislead**

Don't use for trivial questions or when you already have high confidence.

## Routing Logic

```
Classify query → Pick mode/complexity/seats → Invoke
```

### Mode Selection

| Mode | When to Use | Personas |
|------|-------------|----------|
| `council` | General complex decisions, strategic thinking | Reframer, Devil's Advocate, Dreamer, Operator |
| `braintrust` | Building/shipping focus, implementation questions | Builder, Skeptic, Dreamer, Operator |
| `researcher` | Research design, analysis, methodology | Methodologist, Domain Expert, Critical Reviewer, Statistician |
| `general` | Pragmatic problem-solving, less specialized | Pragmatist, Skeptic, Strategist, Architect |

### Complexity

- `full`: 4 frontier models (Claude Sonnet 4.6, GPT-5.4, Gemini 3.1 Pro, Grok 4.20)
- `simple`: 4 lighter models (Claude Haiku 4.5, GPT-5 Mini, Gemini 3 Flash, Grok 4.3)

Use `full` for high-stakes decisions, `simple` for quicker/cheaper deliberation.

## How to Invoke

### From Python

```python
import asyncio
from council import run_deliberation

output = asyncio.run(run_deliberation(
    question="Should we use PostgreSQL or DynamoDB for our event store?",
    context="Event sourcing system, 10k events/sec, need ACID compliance",
    mode="council",
    models=["anthropic/claude-sonnet-4.6", "openai/gpt-5.4"],
    complexity="full"
))

print(output)
```

### From Command Line

```bash
python3 scripts/council.py \
  "Should we use PostgreSQL or DynamoDB?" \
  --context "Event sourcing, 10k events/sec" \
  --mode council \
  --complexity full
```

### From Agent Script

```python
import subprocess

result = subprocess.run([
    "python3", "scripts/council.py",
    "Your question here",
    "--mode", "braintrust",
    "--complexity", "full"
], capture_output=True, text=True)

print(result.stdout)
```

## Passing Context

Context is critical. Include:
- **Technical constraints**: Scale, latency requirements, existing stack
- **Business constraints**: Budget, timeline, team skills
- **Prior attempts**: What you've tried and why it failed
- **Specific concerns**: Security, performance, maintainability

Good context leads to grounded recommendations.

## Output Format

The council returns **Illuminated Minutes** in Markdown:

```markdown
# Council Deliberation: [Your Question]
**Date:** 2026-06-24 | **Mode:** council | **Models:** 4 | **Confidence:** 0.85

---

## Stage 1: Independent Perspectives
[Each model's initial take with their persona]

---

## Stage 2: Cross-Pollination
[Convergence tags showing how models responded to each other]

---

## Synthesis
[Chairman's recommendation, consensus, dissent, and preserved gems]
```

## Override Flags

Control behavior via environment variables:

```bash
# Override default models (comma-separated)
export COUNCIL_MODELS="anthropic/claude-sonnet-4.6,openai/gpt-5.4"

# Override chairman model
export COUNCIL_CHAIRMAN="anthropic/claude-opus-4.5"

# Override chronicle path
export COUNCIL_CHRONICLE_PATH="$HOME/my-council-log.md"

# Required: Your OpenRouter API key
export OPENROUTER_API_KEY="sk-or-v1-..."
```

## Chronicle

Every deliberation appends to `~/.council-of-claude/chronicle.md` (or your custom path). This creates a permanent record of all council decisions for later reference.

## Setup Verification

```bash
python3 -c "import asyncio; from council import check_setup; print(asyncio.run(check_setup()))"
```

Returns `True` if your OpenRouter API key is valid, `False` otherwise.

## Integration Tips

1. **Pre-council research**: Run web/codebase scouts first to gather context
2. **Post-council execution**: Extract the recommendation and pass to a builder agent
3. **Confidence thresholds**: If confidence < 0.7, consider gathering more context
4. **Dissent analysis**: Always read the minority report—it often flags future issues

## Cost & Time

- **Full complexity**: ~30-60s, $0.50-2.00 depending on response lengths
- **Simple complexity**: ~20-40s, $0.10-0.50

Stage 1 is highest cost (4 models reasoning independently). Stage 2 is cheaper (lower reasoning effort). Stage 3 is single model synthesis.

## Troubleshooting

**"ModuleNotFoundError: No module named 'council'"**
- Tests use `sys.path.insert` to import from `scripts/`. If using elsewhere, install as package or adjust path.

**"OPENROUTER_API_KEY environment variable not set"**
- Export your API key before running.

**"Unknown mode: xyz"**
- Valid modes: `council`, `braintrust`, `researcher`, `general`

**One model times out**
- Council continues with remaining models (graceful degradation). Check OpenRouter status if persistent.