AI Counsel

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

Cloud Models Debate(Claude Sonnet, GPT-5.1 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.2-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

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

- 🎯Two Modes:quick(single-round) orconference(multi-round debate)
- 🤖Mixed Adapters: CLI tools (claude, codex, droid, gemini) + HTTP services (ollama, lmstudio, openrouter, nebius)
- ⚡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
- 🔬Evidence-Based Deliberation: Models can read files, search code, list files, and run commands to ground decisions in reality
- 💰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 withquery_decisionstool (finds contradictions, traces evolution, analyzes patterns)
- 🛡️Fault Tolerant: Individual adapter failures don't halt deliberation
- 📝Full Transcripts: Markdown exports with AI-generated summaries
- Install– follow the commands inInstallationto clone the repo, create a virtualenv, and install requirements.
- Configure– set up your MCP client using the.mcp.jsonexample inConfigure in Claude Code.
- Run– start the server withpython server.pyand trigger thedeliberatetool using the examples inUsage.

// Mix local + cloud models, zero API costs for local models mcp__ai-counsel__deliberate({ question: "Should we add unit tests to new features?", participants: [ {cli: "ollama", model: "llama2"}, // Local {cli: "lmstudio", model: "mistral"}, // Local {cli: "claude", model: "sonnet"} // Cloud ], mode: "quick" })

Recommended: Use 7B-8B+ parameter models (Llama-3-8B, Mistral-7B, Qwen-2.5-7B) for reliable structured output and vote formatting.

Not Recommended: Models under 3B parameters (e.g., Llama-3.2-1B) may struggle with complex instructions and produce invalid votes.

Available Models:claude(opus 4.5, sonnet, haiku),codex(gpt-5.2-codex, gpt-5.1-codex-max, gpt-5.1-codex-mini, gpt-5.2),droid,gemini, HTTP adapters (ollama, lmstudio, openrouter). SeeCLI Model Referencefor complete details.

participants: [ {cli: "codex", model: "gpt-5.2-codex", reasoning_effort: "high"}, // Deep reasoning {cli: "droid", model: "gpt-5.1-codex-max", reasoning_effort: "low"} // Fast response ]

- Codex:none,minimal,low,medium,high,xhigh
- Droid:off,low,medium,high
- Config defaults set inconfig.yaml, per-participant overrides at runtime

For model choices and picker workflow, seeModel Registry & Picker.
- Python 3.11+:python3 --version
- 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

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:Usetype: clifor CLI tools andtype: httpfor HTTP adapters (Ollama, LM Studio, OpenRouter).

Control which models are available for selection in the model registry. Each model can be enabled or disabled without removing its definition:

model_registry: claude: - id: "claude-sonnet-4-5-20250929" label: "Claude Sonnet 4.5" tier: "balanced" default: true enabled: true # Model is active and available - id: "claude-opus-4-20250514" label: "Claude Opus 4" tier: "premium" enabled: false # Temporarily disabled (cost control, testing, etc.)

- enabled: true(default) - Model appears inlist_modelsand can be selected for deliberations
- enabled: false- Model is hidden from selection but definition retained for easy re-enabling
- Disabled models cannot be used even if explicitly specified indeliberatecalls
- Default model selection skips disabled models automatically

- Cost Control: Disable expensive models temporarily without losing configuration
- Testing: Enable/disable specific models during integration tests
- Staged Rollout: Configure new models as disabled, enable when ready
- Performance Tuning: Disable slow models during rapid iteration
- Compliance: Temporarily restrict models pending approval

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

→[Complete Guide- Vote structure, examples, integration

…