npm package: @statechange/council
Description: CLI + GUI for orchestrating round-robin AI councilor discussions with structured debate and freeform modes
Latest version: 0.11.0

# @statechange/council

Build a council of AI personas and have them debate any topic. Each councilor has their own LLM backend, model, personality, and source material. Run discussions in a structured **debate** format or an open **freeform** group chat — via the CLI, an Electron GUI, or Claude Code skills.

## Getting Started with Claude Code Skills

The fastest path is to add the skills to [Claude Code](https://claude.com/claude-code). They handle installation, configuration, councilor creation, and running discussions for you.

```bash
npx skills add statechange/ai-council
```

This gives you two skills:

| Skill | What it does |
|-------|-------------|
| `/council-manage` | Create councilors, run discussions, manage your council. Try: *"create a councilor based on Warren Buffett"* or *"run a debate about whether AI should be open source"* |
| `/council-setup-keys` | Finds API keys scattered across your env files and shell profiles, then imports them into `~/.ai-council/config.json` |

The skills will install the `council` CLI automatically if it's not already on your system.

## Install

```bash
# Global install (gives you the `council` command)
npm install -g @statechange/council

# Or run one-off without installing
npx @statechange/council discuss "Should we adopt microservices?"
```

## CLI

### Run a discussion

```bash
# Freeform (default) — open group chat, everyone sees everything
council discuss "Should we pivot to enterprise?" --rounds 3

# Debate — structured constructive/rebuttal format
council discuss "Should AI be open source?" --mode debate --rounds 3

# Pick specific councilors
council discuss "Topic" --councilors ./council/strategist ./council/critic

# Topic from a file
council discuss ./topics/architecture.md
```

### Manage councilors

```bash
council list                                  # Show available councilors
council councilor add ./path/to/councilor   # Register from local directory
council councilor add https://github.com/user/councilors.git  # From git
council councilor remove my-councilor       # Unregister
```

### View history

```bash
council history        # List past discussions
council history <id>   # View a specific discussion
```

### Browse available models

```bash
council models                         # List models for all backends
council models google                  # List models for a specific backend
```

### Configure backends

```bash
council config show                    # See what's configured
council config scan                    # Find API keys across your system
council config scan ~/project/.env     # Scan additional paths
council config import                  # Import discovered keys into config
```

### All CLI options

```
council discuss <topic> [options]

  --mode, -m          freeform or debate (default: freeform)
  --rounds, -r        Number of discussion rounds (default: 2)
  --council, -c       Path to council directory (default: ./council/)
  --councilors       Specific councilor directory paths (space-separated)
  --output, -o        Output directory (default: ./output)
  --format, -f        md, json, or both (default: both)
  --infographic, -i   Generate an infographic after discussion
```

## GUI

The Electron app gives you a visual interface with real-time streaming, point-and-click councilor management, and full discussion history.

```bash
# From the cloned repo
git clone https://github.com/statechange/ai-council.git
cd ai-council
bun install
bun run dev:gui
```

### What you get

- **Discussion page** — Topic input with file attachments, councilor selection chips, freeform/debate mode toggle, real-time streaming of responses, round dividers and interim summaries in debate mode, inject messages mid-discussion
- **Councilors page** — Browse, search, create, edit, and delete councilors with a form editor or raw ABOUT.md editing; register external councilors from local paths or git repos
- **History page** — Browse past discussions, view full transcripts with round summaries, copy as markdown, generate infographics
- **Settings page** — Configure API keys per backend, test connections, see available models

## Discussion Modes

### Freeform

The default. An open group chat where every councilor sees the full conversation history on every turn. The first speaker sets the tone and later speakers react to what's been said. Councilor order stays the same each round.

### Debate

A structured argument format designed to prevent pile-on and anchoring bias:

1. **Round 1 — Constructive**: Each councilor argues their position based *only* on the question. They can't see what anyone else said. Even a "critic" persona has to stand up their own argument first.

2. **Rebuttal rounds (2+)**: Councilors now see the constructive round plus *only* the previous rebuttal round — not the entire history. This keeps context growth bounded. Speaker order is shuffled each round so nobody is always first or last.

3. **Interim summaries**: If a secretary is configured, a brief summary is generated after every round, tracking emerging agreements, disagreements, and shifts in position.

## Configuration

### API Keys

Each backend needs an API key (except Ollama, which runs locally). Keys are resolved in order:

1. `~/.ai-council/config.json` (managed by `council config import` or the GUI)
2. Environment variables: `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GOOGLE_API_KEY`
3. `.env` file in the working directory

### Secretary

Enable post-discussion summaries (and debate interim summaries) by adding a `secretary` block to `~/.ai-council/config.json`:

```json
{
  "backends": { "..." : "..." },
  "secretary": {
    "backend": "anthropic",
    "model": "claude-sonnet-4-6"
  }
}
```

### Supported Backends

| Backend | API Key | Example Models |
|---------|---------|----------------|
| anthropic | `ANTHROPIC_API_KEY` | All Claude models (Opus, Sonnet, Haiku) |
| openai | `OPENAI_API_KEY` | All GPT and o-series models |
| google | `GOOGLE_API_KEY` | All Gemini models (Pro, Flash, Flash-Lite) |
| ollama | None (local) | Any model you've pulled locally |

Each backend supports all current models from its provider. List available models with:

```bash
council models              # All backends
council models anthropic    # Just one
```

## Creating Councilors

A councilor is a directory containing an `ABOUT.md` file with YAML frontmatter and a system prompt:

```
council/
  my-councilor/
    ABOUT.md
    avatar.jpg    # optional
```

### ABOUT.md format

```markdown
---
name: "The Strategist"
description: "Thinks in systems, moats, and long-term positioning"
interests: ["strategy", "markets", "competition"]
backend: "anthropic"
model: "claude-sonnet-4-6"
temperature: 0.7
avatar: "avatar.jpg"
---

You are The Strategist. You sit on a council of experts and bring a
strategic lens to every discussion.

When contributing:
- Think about second and third-order effects
- Consider offensive and defensive strategic positions
- Ground your thinking in frameworks when relevant
- Be direct and opinionated

Keep your responses focused. Aim for 2-4 paragraphs per turn.
```

### Frontmatter fields

| Field | Required | Description |
|-------|----------|-------------|
| `name` | Yes | Display name |
| `description` | Yes | One-line summary of this councilor's perspective |
| `backend` | Yes | `anthropic`, `openai`, `google`, or `ollama` |
| `model` | No | Specific model ID; uses backend default if omitted |
| `temperature` | No | 0.0–2.0; higher = more creative (default varies by backend) |
| `interests` | No | Tags shown in the UI |
| `avatar` | No | Path to local image or URL |

### Included councilors

The package ships with three starter councilors:

| Councilor | Backend | Perspective |
|-----------|---------|-------------|
| **The Strategist** | Anthropic (Haiku) | Strategic business advisor — positioning, growth, competitive advantage |
| **The Creative** | Anthropic (Opus) | Lateral thinker — unexpected analogies, reframing, unconventional connections |
| **The Critic** | Google (Gemini Flash) | Devil's advocate — stress-tests ideas, surfaces assumptions, finds failure modes |

### Building councilors from source material

You can create councilors based on real people or bodies of work by appending reference material below the system prompt. The `/council-manage` skill in Claude Code can automate this — ask it to *"create a councilor based on [person or book]"* and it'll handle downloading source text, writing the system prompt, and assembling the ABOUT.md.

## Logging

Errors are logged to `~/.ai-council/council.log` with timestamps, context tags, and full stack traces. Check this file when a councilor fails to respond or a summary doesn't generate.

## Development

```bash
git clone https://github.com/statechange/ai-council.git
cd ai-council
bun install

bun run dev -- discuss "topic"     # CLI development
bun run dev:gui                    # GUI development
bun run build                      # Build CLI
bun run build:gui                  # Build GUI
```

## License

MIT