CLI Reference

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 only staged changes
ai-council review --staged --pretty

# Review only unstaged changes
ai-council review --unstaged --pretty

# Review both staged and unstaged changes
ai-council review --all --pretty

Git Targeting Options

AI Council provides flexible options for targeting specific commits, branches, and commit ranges for review.

# Review staged/unstaged git changes (auto-detect)
ai-council review --pretty

# Explicitly review only staged changes
ai-council review --staged --pretty

# Explicitly review only unstaged changes
ai-council review --unstaged --pretty

# Review both staged and unstaged changes
ai-council review --all --pretty

# Review current HEAD vs main branch
ai-council review --branch=main --pretty

# Review a specific commit
ai-council review --commit=abc123 --pretty

# Review the last 5 commits on main
ai-council review --range=main~5..main --pretty

# Review all commits on a feature branch
ai-council review --review-branch=feature --pretty

# Review feature branch against develop (instead of main)
ai-council review --review-branch=feature --base=develop --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 --branch=main --pretty

ai-council perf --commit=abc123 --pretty

ai-council arch --review-branch=feature --pretty

ai-council sanity --range=main~3..main --pretty

ai-council decide --agents=security --branch=main --question="Is this auth flow secure?"

Interactive Chat

Run an interactive chat session where you can ask the council multiple questions in a row. Choose an agent set once, then type questions and see verdicts with rationale and agent votes.

ai-council chat

With git context (same options as review commands):

ai-council chat --branch=main
ai-council chat --commit=abc123
ai-council chat --range=main~5..main
ai-council chat --review-branch=feature

At startup you choose the agent set: review, security, perf, arch, or sanity. Then type your question and press Enter. Type exit or quit to end the session.

You can request fix suggestions per-message by including phrases like "with suggestions", "fix examples", or "code examples" in your question, or the AI can infer when you want them. Use --suggestions to always request them. See Fix Suggestions for full details.

Fix Suggestions

When agents vote REVISE or REJECT, they can optionally provide concrete code fix examples. Suggestions are syntax-highlighted and prettified in the terminal, covering JavaScript, TypeScript, Python, Go, Rust, Java, Ruby, PHP, SQL, Shell, and more.

CLI Usage

Add --suggestions to any review command:

# Review with fix examples from dissenting agents
ai-council review --diff --branch=main --suggestions

# Security review with suggestions
ai-council security --branch=main --suggestions

# Chat with suggestions always on
ai-council chat --suggestions

When --suggestions is used with review commands, the output switches from raw JSON to a human-readable format showing the verdict, rationale, agent votes, and fix suggestions in styled boxes.

Chat Mode

In chat mode, you can request suggestions in three ways:

1. --suggestions flag: always request suggestions for every turn.
2. Trigger phrases: include phrases like "with suggestions", "fix examples", "code examples", or "with examples" in your message.
3. AI inference: the tool can automatically detect when your message implies you want fix examples (e.g. "how would I fix this?") and request them for that turn.

MCP / Programmatic

All MCP tools accept an optional suggestions boolean parameter. When true, agents include a "suggestion" field in their vote when they recommend REVISE or REJECT.

Suggestion Rate Limiting (Chat)

When no explicit flag or trigger phrase is used, the AI classifier determines whether to request suggestions. This classifier is rate-limited to prevent excessive API calls. Configure via environment variables:

Pre-Review Context

An opt-in preprocessing stage that runs before the LLM reviewers, extracting and ranking the most relevant code units from your diff or input to give agents better context.

How It Works

1. AST Extraction: Uses tree-sitter to parse TypeScript/JavaScript into an AST and extract semantic code units (functions, classes, methods, interfaces, type aliases). Falls back to line-based chunking for unsupported languages.
2. Embedding Ranking: Each extracted unit is embedded using CodeBERT and ranked by cosine similarity to the review question.
3. Context Injection: The top-k most relevant code units are injected into each reviewer agent's prompt, giving them focused structural context beyond the raw diff.

The entire pipeline is fail-open: if AST extraction, embedding, or any step fails or times out, the review proceeds normally without enriched context.

CLI Usage

# Enable with default settings (top 5 units)
ai-council review --branch=main --pre-context --pretty

# Customize the number of code units injected
ai-council review --branch=main --pre-context-top-k=10 --pretty

# Works with all review types
ai-council security --branch=main --pre-context --pretty
ai-council arch --review-branch=feature --pre-context --pretty

MCP / Programmatic

All MCP tools accept:

• preContext (boolean): enable the AST + embedding pipeline.
• preContextTopK (number): number of top code units to inject (implies preContext, default: 5).

Configuration

Fine-tune the pipeline via environment variables:

Graph Context

AI Council can enrich review prompts with structural graph neighborhood context around changed file paths (Neo4j/Aura, Memgraph, or a generic HTTP graph API). Discovery runs automatically when a usable source is found. Reviews are fail-open: missing graph, missing driver, auth errors, and timeouts never fail the review.

Discovery order

First usable connection wins (walks from cwd up to the git root):

1. Explicit config: ai-council.graph.json or .ai-council/graph.json
2. Env connection: Neo4j, Memgraph, or HTTP variables (see below)
3. Heuristics: docker-compose*.yml / compose*.yml services or images containing neo4j, memgraph, or aura; manifest deps such as neo4j-driver, @neo4j/*, gqlalchemy, or neo4j in package.json, requirements.txt, pyproject.toml, or Cargo.toml (credentials still come from env)
4. Nothing found: skip graph context silently

Config example

{
  "adapter": "neo4j",
  "uri": "bolt://localhost:7687",
  "username": "neo4j",
  "passwordEnv": "NEO4J_PASSWORD",
  "database": "neo4j",
  "http": {
    "url": "https://example/graph/query",
    "headersEnv": "AI_COUNCIL_GRAPH_HTTP_HEADERS_JSON"
  },
  "neighborhood": {
    "depth": 2,
    "maxNodes": 80,
    "maxEdges": 120
  },
  "query": "OPTIONAL Cypher/GQL using $paths only",
  "timeoutMs": 8000
}

Secrets must be referenced by env var names (passwordEnv, headersEnv); never inline passwords.

CLI overrides

# Force graph discovery on
ai-council review --diff --branch=main --graph --pretty

# Disable graph context for this command
ai-council review --diff --branch=main --no-graph --pretty

Deep Analysis

A file-by-file review pipeline that produces structured, line-specific findings instead of the standard single-prompt council vote. Each file in the diff is reviewed individually by a dedicated Deep Reviewer agent, then results are aggregated by the Judge.

How It Works

1. Diff Parsing: The unified diff is parsed into per-file patches. Binary files, snapshots, .d.ts, dist/, sourcemaps, and minified files are automatically skipped.
2. Full-File Context: For each changed file, the full post-change file content is read from disk and included alongside the patch so the LLM has surrounding context, not just hunks (capped at 60k chars per file).
3. Parallel File-Level Review: Files are reviewed in parallel batches (8 concurrent) by the Deep Reviewer agent. Each review returns structured JSON with a summary, recommendation (APPROVE / REVISE / REJECT), confidence score, and an array of findings. If JSON parsing fails, a retry prompt is sent automatically.
4. Concrete Code Findings: Every finding includes the file path, line number, severity, issue description, plus the exact problematicCode and a concrete recommendedCodeChange showing the fix.
5. Aggregation: The Judge agent reviews all per-file results and produces a single overall recommendation, weighting high-severity findings heavily.

Severity Levels

CLI Usage

# Deep file-by-file review against main
ai-council review --branch=main --deep-analysis --pretty

# Combine with suggestions for fix examples
ai-council review --branch=main --deep-analysis --suggestions --pretty

# Works with all git targeting options
ai-council review --staged --deep-analysis --pretty
ai-council review --review-branch=feature --deep-analysis --pretty

When --deep-analysis is used, the output includes a structured findings table showing each file reviewed, its recommendation, and line-level issues with severity and suggestions.

Project-Rule Injection

AI Council automatically discovers and injects project-level rules and conventions into all review prompts (both standard and deep analysis). Rules are loaded from these locations in your repository root:

• .cursorrules
• .cursor/rules/ (all files, recursive)
• .claude/rules/ (all files, recursive)

The combined rules text is capped at 8,000 characters to avoid blowing up context windows. If no rule files are found, the review proceeds normally without injected rules.

MCP / Programmatic

All MCP tools accept an optional deepAnalysis boolean parameter. When true, the review is routed through the file-by-file deep analysis pipeline and the result includes fileReviews and findings arrays.

Agent Review

A two-pass review pipeline powered by the Claude Agent SDK that gives Claude full codebase access to trace callers, read files, check tests, and find dead code, not just review the diff.

How It Works

1. Pass 1 · Surface Scan: All diffs are fed to Claude with no tool access. Claude produces a high-level overview, a priority list of files needing scrutiny, and any immediate risks visible from the diffs alone.
2. Pass 2 · Deep File Analysis: For each changed file, a new session is forked from Pass 1 (inheriting that context) and Claude is given Read, Grep, and Glob tool access. Claude actively explores the codebase: reads full files, searches for callers of changed exports, traces data flow, checks tests, and validates error handling. Reviews run in parallel batches (8 concurrent).
3. Aggregation: Identical to Deep Analysis: the Judge aggregates all per-file results into a single recommendation.

CLI Usage

# Two-pass agent review against main
ai-council review --agent --branch=main --pretty

# Agent review of staged changes
ai-council review --agent --staged --pretty

# Combine with suggestions
ai-council review --agent --branch=main --suggestions --pretty

The --agent flag implies --deep-analysis, so the output uses the same structured findings format with per-file reviews, severity levels, and concrete code suggestions.

Prerequisites

Agent review requires two additional dependencies:

1. Claude Agent SDK: Install with npm install @anthropic-ai/claude-agent-sdk
2. Claude Code CLI: See the Anthropic docs for installation

If the SDK is not installed, the command fails with a clear error message and installation instructions.

MCP / Programmatic

All MCP tools accept an optional agent boolean parameter. When true, the review is routed through the two-pass Claude Agent SDK pipeline (implies deepAnalysis).

Utility Commands

AI Council provides helpful utility commands for setup, debugging, and information.

ai-council tools

ai-council test

🔍 Testing API connectivity...

✅ OpenAI API: Connected (gpt-5.4-mini)
✅ Gemini API: Connected (gemini-3.6-flash)

All APIs operational!

ai-council chat
ai-council chat --branch=main

ai-council --version
ai-council -v

ai-council --help

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 }}
          # Optional: Add Gemini for diverse AI perspectives
          GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
          # Optional: Customize models (defaults shown)
          AI_COUNCIL_MODEL: gpt-5.4-mini
          AI_COUNCIL_GEMINI_MODEL: gemini-3.6-flash
        run: ai-council review --diff --branch=origin/main --ci

Adding Gemini

For the most comprehensive reviews, add your Gemini API key to enable the Gemini Structural Thinker agent. This provides diverse AI perspectives and helps catch edge cases that a single provider might miss.

Customizing Models

You can customize which models power your council by setting environment variables: