True deliberative consensus MCP server where AI models debate and refine positions across multiple rounds.

Cloud Models Debate (Claude Sonnet, GPT-5 Codex, Gemini):

mcp__ai-counsel__deliberate({
  question: "Should we use REST or GraphQL for our new API?",
  participants: [
    {cli: "claude", model: "claude-sonnet-4-5-20250929"},
    {cli: "codex", model: "gpt-5-codex"},
    {cli: "gemini", model: "gemini-2.5-pro"}
  ],
  mode: "conference",
  rounds: 3
})

Result: Converged on hybrid architecture (0.82-0.95 confidence) • View full transcript

Local Models Debate (100% private, zero API costs):

mcp__ai-counsel__deliberate({
  question: "Should we prioritize code quality or delivery speed?",
  participants: [
    {cli: "ollama", model: "llama3.1:8b"},
    {cli: "ollama", model: "mistral:7b"},
    {cli: "ollama", model: "deepseek-r1:8b"}
  ],
  mode: "conference",
  rounds: 2
})

Result: 2 models switched positions after Round 1 debate • View full transcript

AI Counsel enables TRUE deliberative consensus where models see each other's responses and refine positions across multiple rounds:

• Models engage in actual debate (see and respond to each other)
• Multi-round convergence with voting and confidence levels
• Full audit trail with AI-generated summaries
• Automatic early stopping when consensus reaches (saves API costs)

• 🎯 Two Modes: quick (single-round) or conference (multi-round debate)
• 🤖 Mixed Adapters: CLI tools (claude, codex, droid, gemini) + HTTP services (ollama, lmstudio, openrouter)
• ⚡ Auto-Convergence: Stops when opinions stabilize (saves API costs)
• 🗳️ Structured Voting: Models cast votes with confidence levels and rationale
• 🧮 Semantic Grouping: Similar vote options automatically merged (0.70+ similarity)
• 🎛️ Model-Controlled Stopping: Models decide when to stop deliberating
• 💰 Local Model Support: Zero API costs with Ollama, LM Studio, llamacpp
• 🔐 Data Privacy: Keep all data on-premises with self-hosted models
• 🧠 Context Injection: Automatically finds similar past debates and injects context for faster convergence
• 🔍 Semantic Search: Query past decisions with query_decisions tool (finds contradictions, traces evolution, analyzes patterns)
• 🛡️ Fault Tolerant: Individual adapter failures don't halt deliberation
• 📝 Full Transcripts: Markdown exports with AI-generated summaries

git clone https://github.com/blueman82/ai-counsel.git

Get up and running in minutes:

1. Install – follow the commands in Installation to clone the repo, create a virtualenv, and install requirements.
2. Configure – set up your MCP client using the .mcp.json example in Configure in Claude Code.
3. Run – start the server with python server.py and trigger the deliberate tool using the examples in Usage.

For model choices and picker workflow, see Model Registry & Picker.

1. Python 3.11+: python3 --version
2. At least one AI tool (optional - HTTP adapters work without CLI):
   • Claude CLI: https://docs.claude.com/en/docs/claude-code/setup
   • Codex CLI: https://github.com/openai/codex
   • Droid CLI: https://github.com/Factory-AI/factory
   • Gemini CLI: https://github.com/google-gemini/gemini-cli

git clone https://github.com/blueman82/ai-counsel.git
cd ai-counsel
python3 -m venv .venv
source .venv/bin/activate  # macOS/Linux; Windows: .venv\Scripts\activate
pip install -r requirements.txt
python3 -m pytest tests/unit -v  # Verify installation

✅ Ready to use! Server includes core dependencies plus optional convergence backends (scikit-learn, sentence-transformers) for best accuracy.

Edit config.yaml to configure adapters and settings:

adapters:
  claude:
    type: cli
    command: "claude"
    args: ["-p", "--model", "{model}", "--settings", "{\"disableAllHooks\": true}", "{prompt}"]
    timeout: 300

  ollama:
    type: http
    base_url: "http://localhost:11434"
    timeout: 120
    max_retries: 3

defaults:
  mode: "quick"
  rounds: 2
  max_rounds: 5

Note: Use type: cli for CLI tools and type: http for HTTP adapters (Ollama, LM Studio, OpenRouter).

Models automatically converge and stop deliberating when opinions stabilize, saving time and API costs. Status: Converged (≥85% similarity), Refining (40-85%), Diverging (<40%), or Impasse (stable disagreement). Voting takes precedence: when models cast votes, convergence reflects voting outcome.

→ Complete Guide - Thresholds, backends, configuration

Models cast votes with confidence levels (0.0-1.0), rationale, and continue_debate signals. Votes determine consensus: Unanimous (3-0), Majority (2-1), or Tie. Similar options automatically merged at 0.70+ similarity threshold.

→ Complete Guide - Vote structure, examples, integration

Run Ollama, LM Studio, or OpenRouter locally for zero API costs and complete data privacy. Mix with cloud models (Claude, GPT-4) in single deliberation.

→ Setup Guides - Ollama, LM Studio, OpenRouter, cost analysis

Add new CLI tools or HTTP adapters to fit your infrastructure. Simple 3-5 step process with examples and testing patterns.

→ Developer Guide - Step-by-step tutorials, real-world examples

AI Counsel learns from past deliberations to accelerate future decisions. Two core capabilities:

When starting a new deliberation, the system:

• Searches past debates for similar questions (semantic similarity)
• Finds the top-k most relevant decisions (configurable, default: 3)
• Injects context into Round 1 prompts automatically
• Result: Models start with institutional knowledge, converge faster

Query past deliberations programmatically:

• Search similar: Find decisions related to a question
• Find contradictions: Detect conflicting past decisions
• Trace evolution: See how opinions changed over time
• Analyze patterns: Identify recurring themes

Configuration (optional - defaults work out-of-box):

decision_graph:
  enabled: true                       # Auto-injection on by default
  db_path: "decision_graph.db"        # Resolves to project root (works for any user/folder)
  similarity_threshold: 0.6           # Adjust to control context relevance
  max_context_decisions: 3            # How many past decisions to inject

Works for any user from any directory - database path is resolved relative to project root.

→ Quickstart | Configuration | Context Injection

python server.py

Option A: Project Config (Recommended) - Create .mcp.json:

{
  "mcpServers": {
    "ai-counsel": {
      "type": "stdio",
      "command": ".venv/bin/python",
      "args": ["server.py"],
      "env": {}
    }
  }
}

Option B: User Config - Add to ~/.claude.json with absolute paths.

After configuration, restart Claude Code.

• Discover the allowlisted models for each adapter by running the MCP tool list_models.
• Set per-session defaults with set_session_models; leave model blank in deliberate to use those defaults.
• Full instructions and request examples live in Model Registry & Picker.

Quick Mode:

mcp__ai-counsel__deliberate({
  question: "Should we migrate to TypeScript?",
  participants: [{cli: "claude", model: "sonnet"}, {cli: "codex", model: "gpt-5-codex"}],
  mode: "quick"
})

Conference Mode (multi-round):

mcp__ai-counsel__deliberate({
  question: "JWT vs session-based auth?",
  participants: [
    {cli: "claude", model: "sonnet"},
    {cli: "codex", model: "gpt-5-codex"}
  ],
  rounds: 3,
  mode: "conference"
})

Search Past Decisions:

mcp__ai-counsel__query_decisions({
  query: "database choice",
  operation: "search_similar",
  limit: 5
})
// Returns: Similar past deliberations with consensus and similarity scores

// Find contradictions
mcp__ai-counsel__query_decisions({
  operation: "find_contradictions"
})
// Returns: Decisions where consensus conflicts

// Trace evolution
mcp__ai-counsel__query_decisions({
  query: "microservices architecture",
  operation: "trace_evolution"
})
// Returns: How opinions evolved over time on this topic

All deliberations saved to transcripts/ with AI-generated summaries and full debate history.

ai-counsel/
├── server.py                # MCP server entry point
├── config.yaml              # Configuration
├── adapters/                # CLI/HTTP adapters
│   ├── base.py             # Abstract base
│   ├── base_http.py        # HTTP base
│   └── [adapter implementations]
├── deliberation/            # Core engine
│   ├── engine.py           # Orchestration
│   ├── convergence.py      # Similarity detection
│   └── transcript.py       # Markdown generation
├── models/                  # Data models (Pydantic)
├── tests/                   # Unit/integration/e2e tests
└── decision_graph/         # Optional memory system

• Quick Start - 5-minute setup
• Installation - Detailed prerequisites and setup
• Usage Examples - Quick and conference modes

• Convergence Detection - Auto-stop, thresholds, backends
• Structured Voting - Vote structure, consensus types, vote grouping
• Decision Graph Memory - Learning from past decisions

• HTTP Adapters - Ollama, LM Studio, OpenRouter setup
• Configuration Reference - All YAML options
• Migration Guide - From cli_tools to adapters

• Adding Adapters - CLI and HTTP adapter development
• CLAUDE.md - Architecture, development workflow, gotchas
• Model Registry & Picker - Managing allowlisted models and MCP picker tools

• Troubleshooting - HTTP adapter issues
• Decision Graph Docs - Advanced memory features

pytest tests/unit -v                    # Unit tests (fast)
pytest tests/integration -v -m integration  # Integration tests
pytest --cov=. --cov-report=html       # Coverage report

See CLAUDE.md for development workflow and architecture notes.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/your-feature)
3. Write tests first (TDD workflow)
4. Implement feature
5. Ensure all tests pass
6. Submit PR with clear description

MIT License - see LICENSE file

Built with:

• MCP SDK - Model Context Protocol
• Pydantic - Data validation
• pytest - Testing framework

Inspired by the need for true deliberative AI consensus beyond parallel opinion gathering.

Production Ready - Multi-model deliberative consensus with cross-user decision graph memory, structured voting, and adaptive early stopping for critical technical decisions!