AI Council Documentation

Installation

AI Council is distributed as an npm package with pre-compiled binaries for all major platforms.

npm install -g @mugzie/ai-council

This automatically installs the correct binary for your platform:

• macOS - darwin-arm64 (Apple Silicon) or darwin-x64 (Intel)
• Linux - linux-arm64 or linux-x64
• Windows - win32-x64

License Setup

AI Council requires a valid license key to operate. Purchase your license from our store.

Once you have your license key, set it as an environment variable:

export AI_COUNCIL_LICENSE_KEY="your-license-key"

# AI Council License
export AI_COUNCIL_LICENSE_KEY="your-license-key"

Quick Start

Get up and running with AI Council in under a minute.

npm install -g @mugzie/ai-council

export AI_COUNCIL_LICENSE_KEY="your-key"

# OpenAI (recommended)
export OPENAI_API_KEY="sk-..."

# Or Google Gemini
export GEMINI_API_KEY="..."

# Or both for best results!

ai-council review --diff --branch=main --pretty

Basic Usage

AI Council analyzes your git diff and provides recommendations from multiple AI perspectives.

# Review changes against main branch
ai-council review --diff --branch=main --pretty

# Review changes against develop branch
ai-council review --diff --branch=develop --pretty

# Review staged changes only
ai-council review --diff --pretty

Output Formats

Control how results are displayed:

Review Commands

AI Council offers specialized review modes that focus on specific aspects of your code.

ai-council review --diff --pretty

ai-council security --diff --pretty

ai-council perf --diff --pretty

ai-council arch --diff --pretty

ai-council sanity --diff --pretty

CI/CD Mode

Integrate AI Council into your continuous integration pipeline to automatically review pull requests.

name: AI Council Review

on:
  pull_request:
    branches: [main, develop]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      
      - name: Install AI Council
        run: npm install -g @mugzie/ai-council
      
      - name: Run Code Review
        env:
          AI_COUNCIL_LICENSE_KEY: ${{ secrets.AI_COUNCIL_LICENSE_KEY }}
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        run: ai-council review --diff --branch=origin/main --ci

MCP Server

AI Council includes a Model Context Protocol (MCP) server for integration with AI assistants like Claude and Cursor.

ai-council mcp

The MCP server exposes AI Council's functionality as tools that can be invoked by AI assistants, enabling them to request code reviews during conversations.

Claude Integration

Add AI Council to Claude Code for seamless code review within your Claude conversations.

claude mcp add --transport stdio ai-council -- ai-council mcp

Once configured, Claude can invoke AI Council to review code snippets or git diffs during your conversation.

Cursor Integration

Configure AI Council as an MCP server in Cursor for integrated code review.

{
  "mcpServers": {
    "ai-council": {
      "command": "ai-council",
      "args": ["mcp"],
      "env": {
        "AI_COUNCIL_LICENSE_KEY": "your-license-key",
        "OPENAI_API_KEY": "your-openai-key",
        "GEMINI_API_KEY": "your-gemini-key",
        "AI_COUNCIL_MODEL": "gpt-4o-mini",
        "AI_COUNCIL_GEMINI_MODEL": "gemini-2.0-flash"
      }
    }
  }
}

Environment Variables

Configure AI Council's behavior through environment variables.

* At least one of OPENAI_API_KEY or GEMINI_API_KEY is required.

AI Providers

AI Council supports multiple AI providers for diverse perspectives.

OpenAI (Primary)

Used for most agents including Senior Developer, Security, Performance, Architect, and Pragmatist.

export OPENAI_API_KEY="sk-..."

Google Gemini

Powers the Gemini Structural Thinker agent, providing alternative reasoning and challenging assumptions.

export GEMINI_API_KEY="..."

Model Selection

Customize which AI models power your council.

OpenAI Models

Gemini Models

Agents Overview

AI Council assembles a diverse panel of specialized AI agents.

Voting System

Each agent casts a vote with a confidence score. The system uses these to reach a final decision.

Vote Types

Confidence Scores

Each vote includes a confidence score from 0.0 to 1.0:

• 0.8-1.0: High confidence - agent is certain about their assessment
• 0.5-0.8: Moderate confidence - reasonable certainty
• < 0.5: Low confidence - agent automatically abstains

Abstention Rules

Agents abstain in two scenarios:

1. Domain Mismatch: Specialist agents (Security, Performance, Architect) abstain when code doesn't match their domain expertise
2. Low Confidence: Any agent with confidence below 0.5 automatically abstains

Debate System

When Gemini dissents from the majority, AI Council triggers an automated debate to explore the disagreement.

Debate Flow

1. Detection: System detects Gemini's vote differs from majority
2. Escalation: Debate is triggered between Gemini and the strongest majority voice
3. Rebuttal: Majority agent responds to Gemini's concerns
4. Counter: Gemini provides final response (maintain, partial concede, or full concede)
5. Judgment: Judge considers the debate when making final decision

⚡ Debate escalation: Gemini (REJECT) dissents from majority (APPROVE)

1. senior-dev (DEFEND): The null check on line 42 handles the edge case
   Gemini mentioned. The early return pattern is intentional for...

2. gemini (PARTIAL_CONCEDE): I acknowledge the null check, but maintain
   concern about the async race condition that could still occur when...