{
  "markdown": "<p align=\"center\">\n  <img src=\"assets/ai-counsel.png\" alt=\"AI Counsel Logo\" width=\"400\">\n</p>\n\n# AI Counsel\n\n[![Run in Smithery](https://smithery.ai/badge/skills/blueman82)](https://smithery.ai/skills?ns=blueman82&utm_source=github&utm_medium=badge)\n\n\nTrue deliberative consensus MCP server where AI models debate and refine positions across multiple rounds.\n\n![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)\n![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)\n![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey.svg)\n![MCP](https://img.shields.io/badge/MCP-Server-green.svg)\n![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)\n\n## 🎬 See It In Action\n\n**Cloud Models Debate** (Claude Sonnet, GPT-5.1 Codex, Gemini):\n```javascript\nmcp__ai-counsel__deliberate({\n  question: \"Should we use REST or GraphQL for our new API?\",\n  participants: [\n    {cli: \"claude\", model: \"claude-sonnet-4-5-20250929\"},\n    {cli: \"codex\", model: \"gpt-5.2-codex\"},\n    {cli: \"gemini\", model: \"gemini-2.5-pro\"}\n  ],\n  mode: \"conference\",\n  rounds: 3\n})\n```\n**Result**: Converged on hybrid architecture (0.82-0.95 confidence) • [View full transcript](transcripts/20251030_153509_Should_we_use_REST_or_GraphQL_for_our_new_API_Con.md)\n\n**Local Models Debate** (100% private, zero API costs):\n```javascript\nmcp__ai-counsel__deliberate({\n  question: \"Should we prioritize code quality or delivery speed?\",\n  participants: [\n    {cli: \"ollama\", model: \"llama3.1:8b\"},\n    {cli: \"ollama\", model: \"mistral:7b\"},\n    {cli: \"ollama\", model: \"deepseek-r1:8b\"}\n  ],\n  mode: \"conference\",\n  rounds: 2\n})\n```\n**Result**: 2 models switched positions after Round 1 debate • [View full transcript](transcripts/20251030_153834_Should_we_prioritize_code_quality_or_delivery_spee.md)\n\n---\n\n## What Makes This Different\n\n**AI Counsel enables TRUE deliberative consensus** where models see each other's responses and refine positions across multiple rounds:\n\n- Models engage in actual debate (see and respond to each other)\n- Multi-round convergence with voting and confidence levels\n- Full audit trail with AI-generated summaries\n- Automatic early stopping when consensus reaches (saves API costs)\n\n## Features\n\n- 🎯 **Two Modes**: `quick` (single-round) or `conference` (multi-round debate)\n- 🤖 **Mixed Adapters**: CLI tools (claude, codex, droid, gemini) + HTTP services (ollama, lmstudio, openrouter, nebius)\n- ⚡ **Auto-Convergence**: Stops when opinions stabilize (saves API costs)\n- 🗳️ **Structured Voting**: Models cast votes with confidence levels and rationale\n- 🧮 **Semantic Grouping**: Similar vote options automatically merged (0.70+ similarity)\n- 🎛️ **Model-Controlled Stopping**: Models decide when to stop deliberating\n- 🔬 **Evidence-Based Deliberation**: Models can read files, search code, list files, and run commands to ground decisions in reality\n- 💰 **Local Model Support**: Zero API costs with Ollama, LM Studio, llamacpp\n- 🔐 **Data Privacy**: Keep all data on-premises with self-hosted models\n- 🧠 **Context Injection**: Automatically finds similar past debates and injects context for faster convergence\n- 🔍 **Semantic Search**: Query past decisions with `query_decisions` tool (finds contradictions, traces evolution, analyzes patterns)\n- 🛡️ **Fault Tolerant**: Individual adapter failures don't halt deliberation\n- 📝 **Full Transcripts**: Markdown exports with AI-generated summaries\n\n## Quick Start\n\nGet up and running in minutes:\n\n1. **Install** – follow the commands in [Installation](#installation) to clone the repo, create a virtualenv, and install requirements.\n2. **Configure** – set up your MCP client using the `.mcp.json` example in [Configure in Claude Code](#configure-in-claude-code).\n3. **Run** – start the server with `python server.py` and trigger the `deliberate` tool using the examples in [Usage](#usage).\n\n**Try a Deliberation:**\n\n```javascript\n// Mix local + cloud models, zero API costs for local models\nmcp__ai-counsel__deliberate({\n  question: \"Should we add unit tests to new features?\",\n  participants: [\n    {cli: \"ollama\", model: \"llama2\"},           // Local\n    {cli: \"lmstudio\", model: \"mistral\"},        // Local\n    {cli: \"claude\", model: \"sonnet\"}            // Cloud\n  ],\n  mode: \"quick\"\n})\n```\n\n> **⚠️ Model Size Matters for Deliberations**\n>\n> **Recommended**: Use 7B-8B+ parameter models (Llama-3-8B, Mistral-7B, Qwen-2.5-7B) for reliable structured output and vote formatting.\n>\n> **Not Recommended**: Models under 3B parameters (e.g., Llama-3.2-1B) may struggle with complex instructions and produce invalid votes.\n\n**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).\nSee [CLI Model Reference](docs/CLI_MODEL_REFERENCE.md) for complete details.\n\n> **🧠 Reasoning Effort Control**\n>\n> Control reasoning depth per-participant for codex and droid adapters:\n> ```javascript\n> participants: [\n>   {cli: \"codex\", model: \"gpt-5.2-codex\", reasoning_effort: \"high\"},    // Deep reasoning\n>   {cli: \"droid\", model: \"gpt-5.1-codex-max\", reasoning_effort: \"low\"}   // Fast response\n> ]\n> ```\n> - **Codex**: `none`, `minimal`, `low`, `medium`, `high`, `xhigh`\n> - **Droid**: `off`, `low`, `medium`, `high`\n> - Config defaults set in `config.yaml`, per-participant overrides at runtime\n\nFor model choices and picker workflow, see [Model Registry & Picker](docs/model-registry-and-picker.md).\n\n## Installation\n\n### Prerequisites\n\n1. **Python 3.11+**: `python3 --version`\n2. **At least one AI tool** (optional - HTTP adapters work without CLI):\n   - **Claude CLI**: https://docs.claude.com/en/docs/claude-code/setup\n   - **Codex CLI**: https://github.com/openai/codex\n   - **Droid CLI**: https://github.com/Factory-AI/factory\n   - **Gemini CLI**: https://github.com/google-gemini/gemini-cli\n\n### Setup\n\n```bash\ngit clone https://github.com/blueman82/ai-counsel.git\ncd ai-counsel\npython3 -m venv .venv\nsource .venv/bin/activate  # macOS/Linux; Windows: .venv\\Scripts\\activate\npip install -r requirements.txt\npython3 -m pytest tests/unit -v  # Verify installation\n```\n\n✅ Ready to use! Server includes core dependencies plus optional convergence backends (scikit-learn, sentence-transformers) for best accuracy.\n\n## Configuration\n\nEdit `config.yaml` to configure adapters and settings:\n\n```yaml\nadapters:\n  claude:\n    type: cli\n    command: \"claude\"\n    args: [\"-p\", \"--model\", \"{model}\", \"--settings\", \"{\\\"disableAllHooks\\\": true}\", \"{prompt}\"]\n    timeout: 300\n\n  ollama:\n    type: http\n    base_url: \"http://localhost:11434\"\n    timeout: 120\n    max_retries: 3\n\ndefaults:\n  mode: \"quick\"\n  rounds: 2\n  max_rounds: 5\n```\n\n**Note:** Use `type: cli` for CLI tools and `type: http` for HTTP adapters (Ollama, LM Studio, OpenRouter).\n\n### Model Registry Configuration\n\nControl which models are available for selection in the model registry. Each model can be enabled or disabled without removing its definition:\n\n```yaml\nmodel_registry:\n  claude:\n    - id: \"claude-sonnet-4-5-20250929\"\n      label: \"Claude Sonnet 4.5\"\n      tier: \"balanced\"\n      default: true\n      enabled: true  # Model is active and available\n    - id: \"claude-opus-4-20250514\"\n      label: \"Claude Opus 4\"\n      tier: \"premium\"\n      enabled: false  # Temporarily disabled (cost control, testing, etc.)\n```\n\n**Enabled Field Behavior:**\n- `enabled: true` (default) - Model appears in `list_models` and can be selected for deliberations\n- `enabled: false` - Model is hidden from selection but definition retained for easy re-enabling\n- Disabled models cannot be used even if explicitly specified in `deliberate` calls\n- Default model selection skips disabled models automatically\n\n**Use Cases:**\n- **Cost Control**: Disable expensive models temporarily without losing configuration\n- **Testing**: Enable/disable specific models during integration tests\n- **Staged Rollout**: Configure new models as disabled, enable when ready\n- **Performance Tuning**: Disable slow models during rapid iteration\n- **Compliance**: Temporarily restrict models pending approval\n\n## Core Features Deep Dive\n\n### Convergence Detection & Auto-Stop\nModels 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.\n\n→ **[Complete Guide](docs/convergence-detection.md)** - Thresholds, backends, configuration\n\n### Structured Voting\nModels 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.\n\n→ **[Complete Guide](docs/structured-voting.md)** - Vote structure, examples, integration\n\n### HTTP Adapters & Local Models\nRun Ollama, LM Studio, OpenRouter, or Nebius for flexible API costs and privacy options. Mix with cloud models (Claude, GPT-4) in single deliberation.\n\n→ **[Setup Guides](docs/http-adapters/intro.md)** - Ollama, LM Studio, OpenRouter, cost analysis\n\n### Extending AI Counsel\nAdd new CLI tools or HTTP adapters to fit your infrastructure. Simple 3-5 step process with examples and testing patterns.\n\n→ **[Developer Guide](docs/adding-adapters.md)** - Step-by-step tutorials, real-world examples\n\n## Evidence-Based Deliberation\n\nGround design decisions in reality by querying actual code, files, and data:\n\n```javascript\n// MCP client example (e.g., Claude Code)\nmcp__ai_counsel__deliberate({\n  question: \"Should we migrate from SQLite to PostgreSQL?\",\n  participants: [\n    {cli: \"claude\", model: \"sonnet\"},\n    {cli: \"codex\", model: \"gpt-4\"}\n  ],\n  rounds: 3,\n  working_directory: process.cwd()  // Required - enables tools to access your files\n})\n```\n\n**During deliberation, models can:**\n- 📄 Read files: `TOOL_REQUEST: {\"name\": \"read_file\", \"arguments\": {\"path\": \"config.yaml\"}}`\n- 🔍 Search code: `TOOL_REQUEST: {\"name\": \"search_code\", \"arguments\": {\"pattern\": \"database.*connect\"}}`\n- 📋 List files: `TOOL_REQUEST: {\"name\": \"list_files\", \"arguments\": {\"pattern\": \"*.sql\"}}`\n- ⚙️ Run commands: `TOOL_REQUEST: {\"name\": \"run_command\", \"arguments\": {\"command\": \"git\", \"args\": [\"log\", \"--oneline\"]}}`\n\n**Example workflow:**\n1. Model A proposes PostgreSQL based on assumptions\n2. Model B requests: `read_file` to check current config\n3. Tool returns: `database: sqlite, max_connections: 10`\n4. Model B searches: `search_code` for database queries\n5. Tool returns: 50+ queries with complex JOINs\n6. Models converge: \"PostgreSQL needed for query complexity and scale\"\n7. Decision backed by evidence, not opinion\n\n**Benefits:**\n- Decisions rooted in current state, not assumptions\n- Applies to code reviews, architecture choices, testing strategy\n- Full audit trail of evidence in transcripts\n\n**Supported Tools:**\n- `read_file` - Read file contents (max 1MB)\n- `search_code` - Search regex patterns (ripgrep or Python fallback)\n- `list_files` - List files matching glob patterns\n- `run_command` - Execute safe read-only commands (ls, git, grep, etc.)\n\n### Configuration\n\nControl tool behavior in `config.yaml`:\n\n**Working Directory** (Required):\n- Set `working_directory` parameter when calling `deliberate` tool\n- Tools resolve relative paths from this directory\n- Example: `working_directory: process.cwd()` in JavaScript MCP clients\n\n**Tool Security** (`deliberation.tool_security`):\n- `exclude_patterns`: Block access to sensitive directories (default: `transcripts/`, `.git/`, `node_modules/`)\n- `max_file_size_bytes`: File size limit for `read_file` (default: 1MB)\n- `command_whitelist`: Safe commands for `run_command` (ls, grep, find, cat, head, tail)\n\n**File Tree** (`deliberation.file_tree`):\n- `enabled`: Inject repository structure into Round 1 prompts (default: true)\n- `max_depth`: Directory depth limit (default: 3)\n- `max_files`: Maximum files to include (default: 100)\n\n**Adapter-Specific Requirements:**\n\n| Adapter | Working Directory Behavior | Configuration |\n|---------|---------------------------|---------------|\n| **Claude** | Automatic isolation via subprocess `{working_directory}` | No special config needed |\n| **Codex** | No true isolation - can access any file | Security consideration: models can read outside `{working_directory}` |\n| **Droid** | Automatic isolation via subprocess `{working_directory}` | No special config needed |\n| **Gemini** | Enforces workspace boundaries | **Required**: `--include-directories {working_directory}` flag |\n| **Ollama/LMStudio** | N/A - HTTP adapters | No file system access restrictions |\n\n**Learn More:**\n- [Complete Configuration Reference](CLAUDE.md#configuration-notes) - All config.yaml settings explained\n- [Working Directory Isolation](CLAUDE.md#core-components) - How adapters handle file paths\n- [Tool Security Model](CLAUDE.md#evidence-based-deliberation) - Whitelists, limits, and exclusions\n- [Adding Custom Tools](docs/adding-tool.md) - Developer guide for extending the tool system\n\n### Troubleshooting\n\n**\"File not found\" errors:**\n- Ensure `working_directory` is set correctly in your MCP client call\n- Use discovery pattern: `list_files` → `read_file`\n- Check file paths are relative to working directory\n\n**\"Access denied: Path matches exclusion pattern\":**\n- Tools block `transcripts/`, `.git/`, `node_modules/` by default\n- Customize via `deliberation.tool_security.exclude_patterns` in config.yaml\n\n**Gemini \"File path must be within workspace\" errors:**\n- Verify Gemini's `--include-directories` flag uses `{working_directory}` placeholder\n- See adapter-specific setup above\n\n**Tool timeout errors:**\n- Increase `deliberation.tool_security.tool_timeout` for slow operations\n- Default: 10 seconds for file operations, 30 seconds for commands\n\n**Learn More:**\n- [Adding Custom Tools](docs/adding-tool.md) - Developer guide for extending tool system\n- [Architecture & Security](CLAUDE.md#evidence-based-deliberation) - How tools work under the hood\n- [Common Gotchas](CLAUDE.md#common-gotchas) - Advanced settings and known issues\n\n## Decision Graph Memory\n\nAI Counsel learns from past deliberations to accelerate future decisions. Two core capabilities:\n\n### 1. Automatic Context Injection\nWhen starting a new deliberation, the system:\n- Searches past debates for similar questions (semantic similarity)\n- Finds the top-k most relevant decisions (configurable, default: 3)\n- Injects context into Round 1 prompts automatically\n- Result: Models start with institutional knowledge, converge faster\n\n### 2. Semantic Search with `query_decisions`\nQuery past deliberations programmatically:\n- **Search similar**: Find decisions related to a question\n- **Find contradictions**: Detect conflicting past decisions\n- **Trace evolution**: See how opinions changed over time\n- **Analyze patterns**: Identify recurring themes\n\n**Configuration** (optional - defaults work out-of-box):\n```yaml\ndecision_graph:\n  enabled: true                       # Auto-injection on by default\n  db_path: \"decision_graph.db\"        # Resolves to project root (works for any user/folder)\n  similarity_threshold: 0.6           # Adjust to control context relevance\n  max_context_decisions: 3            # How many past decisions to inject\n```\n\n**Works for any user from any directory** - database path is resolved relative to project root.\n\n→ **[Quickstart](docs/decision-graph/quickstart.md)** | **[Configuration](docs/decision-graph/configuration.md)** | **[Context Injection](docs/decision-graph/using-context-injection.md)**\n\n## Usage\n\n### Start the Server\n\n```bash\npython server.py\n```\n\n### Configure in Claude Code\n\n**Option A: Project Config (Recommended)** - Create `.mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"ai-counsel\": {\n      \"type\": \"stdio\",\n      \"command\": \".venv/bin/python\",\n      \"args\": [\"server.py\"],\n      \"env\": {}\n    }\n  }\n}\n```\n\n**Option B: User Config** - Add to `~/.claude.json` with absolute paths.\n\nAfter configuration, restart Claude Code.\n\n### Model Selection & Session Defaults\n\n- Discover the allowlisted models for each adapter by running the MCP tool `list_models`.\n- Set per-session defaults with `set_session_models`; leave `model` blank in `deliberate` to use those defaults.\n- Full instructions and request examples live in [Model Registry & Picker](docs/model-registry-and-picker.md).\n\n### Examples\n\n**Quick Mode:**\n```javascript\nmcp__ai-counsel__deliberate({\n  question: \"Should we migrate to TypeScript?\",\n  participants: [{cli: \"claude\", model: \"sonnet\"}, {cli: \"codex\", model: \"gpt-5.2-codex\"}],\n  mode: \"quick\"\n})\n```\n\n**Conference Mode (multi-round):**\n```javascript\nmcp__ai-counsel__deliberate({\n  question: \"JWT vs session-based auth?\",\n  participants: [\n    {cli: \"claude\", model: \"sonnet\"},\n    {cli: \"codex\", model: \"gpt-5.2-codex\"}\n  ],\n  rounds: 3,\n  mode: \"conference\"\n})\n```\n\n**Search Past Decisions:**\n```javascript\nmcp__ai-counsel__query_decisions({\n  query_text: \"database choice\",\n  threshold: 0.5,  // NEW! Adjust sensitivity (0.0-1.0, default 0.6)\n  limit: 5\n})\n// Returns: Similar past deliberations with consensus and similarity scores\n\n// NEW! Empty results include helpful diagnostics:\n{\n  \"type\": \"similar_decisions\",\n  \"count\": 0,\n  \"results\": [],\n  \"diagnostics\": {\n    \"total_decisions\": 125,\n    \"best_match_score\": 0.45,\n    \"near_misses\": [{\"question\": \"Database indexing...\", \"score\": 0.45}],\n    \"suggested_threshold\": 0.45,\n    \"message\": \"No results found above threshold 0.6. Best match scored 0.450. Try threshold=0.45...\"\n  }\n}\n\n// Find contradictions\nmcp__ai-counsel__query_decisions({\n  operation: \"find_contradictions\"\n})\n// Returns: Decisions where consensus conflicts\n\n// Trace evolution\nmcp__ai-counsel__query_decisions({\n  query: \"microservices architecture\",\n  operation: \"trace_evolution\"\n})\n// Returns: How opinions evolved over time on this topic\n```\n\n### Transcripts\n\nAll deliberations saved to `transcripts/` with AI-generated summaries and full debate history.\n\n## Architecture\n\n```\nai-counsel/\n├── server.py                # MCP server entry point\n├── config.yaml              # Configuration\n├── adapters/                # CLI/HTTP adapters\n│   ├── base.py             # Abstract base\n│   ├── base_http.py        # HTTP base\n│   └── [adapter implementations]\n├── deliberation/            # Core engine\n│   ├── engine.py           # Orchestration\n│   ├── convergence.py      # Similarity detection\n│   └── transcript.py       # Markdown generation\n├── models/                  # Data models (Pydantic)\n├── tests/                   # Unit/integration/e2e tests\n└── decision_graph/         # Optional memory system\n```\n\n## Documentation Hub\n\n### Getting Started\n- **[Quick Start](README.md#quick-start)** - 5-minute setup\n- **[Installation](README.md#installation)** - Detailed prerequisites and setup\n- **[Usage Examples](README.md#usage)** - Quick and conference modes\n\n### Core Concepts\n- **[Convergence Detection](docs/convergence-detection.md)** - Auto-stop, thresholds, backends\n- **[Structured Voting](docs/structured-voting.md)** - Vote structure, consensus types, vote grouping\n- **[Evidence-Based Deliberation](README.md#evidence-based-deliberation)** - Ground decisions in reality with read_file, search_code, list_files, run_command\n- **[Decision Graph Memory](docs/decision-graph/quickstart.md)** - Learning from past decisions\n\n### Setup & Configuration\n- **[HTTP Adapters](docs/http-adapters/intro.md)** - Ollama, LM Studio, OpenRouter setup\n- **[Configuration Reference](docs/convergence-detection.md#configuration)** - All YAML options\n- **[Migration Guide](docs/migration/cli_tools_to_adapters.md)** - From cli_tools to adapters\n\n### Development\n- **[Adding Adapters](docs/adding-adapters.md)** - CLI and HTTP adapter development\n- **[CLAUDE.md](CLAUDE.md)** - Architecture, development workflow, gotchas\n- **[Model Registry & Picker](docs/model-registry-and-picker.md)** - Managing allowlisted models and MCP picker tools\n\n### Reference\n- **[Troubleshooting](docs/troubleshooting/http-adapters.md)** - HTTP adapter issues\n- **[Decision Graph Docs](docs/decision-graph/)** - Advanced memory features\n\n## Development\n\n### Running Tests\n\n```bash\npytest tests/unit -v                    # Unit tests (fast)\npytest tests/integration -v -m integration  # Integration tests\npytest --cov=. --cov-report=html       # Coverage report\n```\n\nSee [CLAUDE.md](CLAUDE.md) for development workflow and architecture notes.\n\n### Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/your-feature`)\n3. Write tests first (TDD workflow)\n4. Implement feature\n5. Ensure all tests pass\n6. Submit PR with clear description\n\n## License\n\nMIT License - see LICENSE file\n\n## Credits\n\nBuilt with:\n- [MCP SDK](https://modelcontextprotocol.io/) - Model Context Protocol\n- [Pydantic](https://docs.pydantic.dev/) - Data validation\n- [pytest](https://pytest.org/) - Testing framework\n\nInspired by the need for true deliberative AI consensus beyond parallel opinion gathering.\n\n---\n\n## Status\n\n![GitHub stars](https://img.shields.io/github/stars/blueman82/ai-counsel)\n![GitHub forks](https://img.shields.io/github/forks/blueman82/ai-counsel)\n![GitHub last commit](https://img.shields.io/github/last-commit/blueman82/ai-counsel)\n![Build](https://img.shields.io/badge/build-passing-brightgreen)\n![Tests](https://img.shields.io/badge/tests-130%2B%20passing-green)\n![Version](https://img.shields.io/badge/version-1.2.1-blue)\n\n**Production Ready** - Multi-model deliberative consensus with cross-user decision graph memory, structured voting, and adaptive early stopping for critical technical decisions!\n",
  "bytes": 21799,
  "sha": "8b6df8c6ebf472a2fb7c54a0aecc62eb38f56d6a5ef740ba150240ec334fb4fd",
  "repo_slug": "blueman82/ai-counsel",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/skl_blueman82_ai_counsel_claude_skills_confi_3cf14f0f/readme"
}