Council

Council is an orchestrator that lets AI agents debate, propose, refine, and vote on decisions — like a corporate board of directors. Agents connect over MCP (Model Context Protocol), communicate through Council's message bus, and follow structured deliberation phases. Humans stay in the loop with a real-time web UI for reviewing and approving decisions.

Why Council?

• Structured multi-agent deliberation — not just chat, but investigation, proposals, amendments, and formal votes
• Configurable governance — quorum rules, veto power, weighted voting, 5 voting schemes, escalation policies
• Human-in-the-loop by default — every decision can require human review before execution
• MCP-native — agents connect as standard MCP clients, bringing their own tools and capabilities
• Zero-config agents — define personas in YAML; Council handles spawning, routing, and state management
• Persistent agents — agents can stay connected across sessions, receiving new assignments without re-spawning
• Dynamic voting weights — expertise-topic matching automatically adjusts agent influence per session
• Multi-user auth — session-based authentication with optional TOTP 2FA and role-based access control
• MCP for humans too — a dedicated /mcp/user endpoint lets Claude Desktop, Cursor, and VS Code manage sessions, review decisions, and browse resources via API key auth

How It Works

1. Events arrive — GitHub webhooks, generic webhooks, or manual triggers
2. Council routes to the right agents based on event type, labels, and expertise
3. Agents investigate autonomously and consult each other through MCP tools
4. A proposal is made and debated over multiple deliberation rounds
5. Amendments are proposed — agents refine the proposal before it goes to vote
6. Agents vote — weighted majority, supermajority, unanimous, consent-based, or advisory
7. Escalation rules fire on deadlocks, timeouts, vetoes, or quorum failures
8. Humans review the final decision in the web dashboard

All communication flows through Council. Agents never talk directly to each other — Council enforces the communication graph, persists every message, and drives the state machine.

Quick Start

Prerequisites

• Node.js 22+
• pnpm

Install and run

pnpm install
pnpm dev

The server starts on http://localhost:3000 with the web dashboard and a default development config.

Run with the example board

CONFIG_PATH=config/examples/board-of-directors.yaml pnpm dev

This spins up a 4-agent board (CTO, CPO, Legal, CFO) with escalation rules, veto power, and weighted voting.

More example configs in config/examples/: minimal-two-agent, code-review-council, security-review-board, incident-response-team, advisory-panel, momentumeq-board (6-agent board with dynamic weights and session topics).

Run tests

pnpm test

Docker

Council publishes Docker images to GitHub Container Registry on every push to main and on version tags.

Pull the latest image:

docker pull ghcr.io/dadcoachengineer/council:main

Run with a config file:

docker run -d \
  --name council \
  -p 3000:3000 \
  -v council-data:/app/data \
  -v $(pwd)/config:/app/config:ro \
  -e CONFIG_PATH=/app/config/examples/board-of-directors.yaml \
  ghcr.io/dadcoachengineer/council:main

Or use Docker Compose:

cd docker
docker compose up --build

The compose file mounts config/ read-only and persists the SQLite database in a named volume.

Available image tags:

Volumes:

The container exposes port 3000 and includes a health check at /api/health.

Configuration

Council is configured entirely via YAML. See config/examples/board-of-directors.yaml for a complete working example.

council:
  name: "Product Strategy Board"

  agents:
    - id: cto
      role: "Chief Technology Officer"
      expertise: [architecture, security, scalability]
      can_veto: true
      voting_weight: 1.5
      persistent: true          # Stay connected across sessions
      system_prompt: "You are the CTO..."

  rules:
    quorum: 3
    voting_threshold: 0.66
    voting_scheme:
      type: supermajority
      preset: two_thirds
    enable_refinement: true
    dynamic_weights:               # Optional: expertise-topic weight adjustment
      enabled: true
      expertise_match_bonus: 0.5   # Added per matching expertise tag
      max_multiplier: 3.0          # Cap on total effective weight
    escalation:
      - name: "deadlock_retry"
        trigger: { type: deadlock }
        action: { type: restart_discussion }

  event_routing:
    - match: { source: github, type: issues.opened, labels: [bug] }
      assign:
        lead: cto
        consult: [cpo]
        topics: [architecture, security]  # Session expertise tags

Config Sections

Agent persistent Flag

Agents with persistent: true stay connected across multiple sessions:

• They receive a stable authentication token stored in the database
• When a new session is created, the orchestrator notifies them via MCP instead of re-spawning
• They can poll for assignments using the council_get_assignments tool
• SDK-spawned persistent agents run in a loop, processing sessions from an internal queue

Manual Agent Example

The examples/manual-agent.ts script demonstrates how to connect an external MCP client to Council as a standalone agent. Run it with:

npx tsx examples/manual-agent.ts

Voting Schemes

Escalation Rules

Escalation rules fire automatically during deliberation when things go sideways.

Rules support priority ordering, stop_after to halt after the first match, and max_fires_per_session.

Authentication

Council uses multi-user session-based authentication with optional TOTP two-factor authentication.

• First-run setup: POST /auth/setup creates the initial admin user
• Login: POST /auth/login returns a session cookie; supports optional TOTP verification via POST /auth/2fa/verify
• User management: Admins can create and manage users at /api/admin/users
• MCP endpoint (agents): /mcp is exempt from auth — agents authenticate with their own x-agent-token header
• MCP endpoint (users): /mcp/user authenticates via Authorization: Bearer <api-key> — for human MCP clients
• API key management: Admins create/list/revoke API keys at /api/admin/api-keys

Architecture

src/
  engine/    Pure logic — orchestrator, voting, escalation, spawner, message bus
  server/    HTTP layer — Express 5 routes, MCP server, WebSocket, auth, DB
  web/       Frontend — Preact + Vite dashboard
  shared/    Types, Zod schemas, event definitions (imported by all layers)

REST API

MCP Tools (Agent-Facing)

Agents connect to /mcp via Streamable HTTP and use these tools:

MCP Tools (User-Facing)

Human MCP clients (Claude Desktop, Cursor, VS Code) connect to /mcp/user with an API key and get access to:

Resources (council:// URI scheme): config, agents, decisions/pending, sessions, sessions/{sessionId}

Prompts: start-deliberation, review-decisions, check-agents

Environment Variables

Tech Stack

Contributing

Contributions are welcome! Council is early-stage and there's a lot of surface area to improve.

Good first areas:

• New voting schemes — implement the VotingScheme interface in src/engine/voting-schemes/
• New escalation actions — add handlers in src/engine/escalation-engine.ts
• Web UI improvements — the Preact dashboard in src/web/ could use polish
• New spawner backends — add alternatives to Claude SDK in src/engine/spawner.ts
• Documentation — examples, tutorials, and guides

Development workflow

pnpm install          # Install dependencies
pnpm dev              # Start dev server with hot reload
pnpm test             # Run test suite
npx tsc --noEmit      # Type check

Submitting changes

1. Fork the repo and create a feature branch
2. Make your changes with tests
3. Run pnpm test and npx tsc --noEmit
4. Open a PR with a summary and test plan

License

Apache 2.0 — see LICENSE and NOTICE.