AI Consultants v5.1.1

Coverage, not a single guess. A panel of up to 10 frontier models from different vendors fans out on your question in parallel and hands you the union of what they collectively see — the risks, edge cases, and approaches a single model misses.

Table of Contents

• Why AI Consultants?
• Quick Start
• Prerequisites
• Supported CLI Agents
  • Claude Code
  • OpenAI Codex CLI
  • Gemini CLI
  • Cursor / Copilot / Windsurf
  • Standalone Bash
• Consultants
• Quality Tiers
• Configuration
  • Configuration Recipes
• How It Works
• Best Practices
• Documentation
• Changelog
• License

Why AI Consultants?

A single model gives you a single guess — and it misses whatever falls in its blind spots. AI Consultants fans your question out to a panel of models from different vendors and returns the union of their distinct answers: the point one model raised and the others didn't is exactly the value.

• Cross-vendor diversity → coverage — different model families have different blind spots, so the union covers what any one misses. On open-ended questions ("what could go wrong with this design?", "enumerate the risks") a diverse panel covers materially more of the answer space than one strong model — or than sampling one model repeatedly.
• Parallel fan-out — every consultant runs at once; no serial deliberation rounds.
• Coverage synthesis — the default synthesis is the deduplicated union of every distinct point, not a single voted winner (use --strategy compare_only for a side-by-side, or majority for a blended recommendation).
• 10 supported consultants with distinct personas (Architect, Pragmatist, Devil's Advocate, …) — the personas deliberately decorrelate the panel.
• Best for breadth — threat-modeling, design review, "what am I missing?", exhaustive enumeration. For a single-answer factual or defect-finding question, one strong model is usually enough.

Quick Start

Get started in 30 seconds:

Option A: npx (recommended)

# Run directly - no install needed
npx ai-consultants "How should I structure my authentication system?"

# With a preset
npx ai-consultants --preset balanced "Redis or Memcached?"

# Run diagnostics
npx ai-consultants doctor --fix

# Install slash commands for Claude Code
npx ai-consultants install

Option B: curl | bash (Claude Code skill)

# Install the skill
curl -fsSL https://raw.githubusercontent.com/matteoscurati/ai-consultants/main/scripts/install.sh | bash

# Ask your first question
/ai-consultants:consult "How should I structure my authentication system?"

Update & Uninstall

# npx always runs latest (or pin a version)
npx ai-consultants@latest "question"

# curl | bash update
~/.claude/skills/ai-consultants/scripts/install.sh --update

# Uninstall (curl | bash only)
~/.claude/skills/ai-consultants/scripts/install.sh --uninstall

Prerequisites

Before installing AI Consultants, ensure you have the following dependencies installed.

Required Dependencies

| Dependency | Purpose | |------------|---------| | jq | JSON processing | | curl | HTTP requests and connectivity | | Bash 4.0+ | Script execution (macOS ships with 3.2) |

Installation by Platform

macOS

# Install Homebrew if not already installed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install required dependencies
brew install jq bash coreutils

# Verify installation
jq --version && bash --version | head -1

Note: macOS ships with Bash 3.2. The Homebrew version (4.x) is installed to /opt/homebrew/bin/bash.

Linux (Ubuntu/Debian)

# Install required dependencies
sudo apt-get update
sudo apt-get install -y jq curl bash

# Verify installation
jq --version && bash --version | head -1

Linux (Fedora/RHEL/CentOS)

# Install required dependencies
sudo dnf install -y jq curl bash

# Verify installation
jq --version && bash --version | head -1

Linux (Arch)

# Install required dependencies
sudo pacman -S jq curl bash

# Verify installation
jq --version && bash --version | head -1

Windows

Use WSL (Windows Subsystem for Linux):

# Install WSL (run in PowerShell as Administrator)
wsl --install

# After restart, open WSL and follow Linux instructions
sudo apt-get update
sudo apt-get install -y jq curl bash

Alternatively, use Git Bash or MSYS2 with the required packages.

Optional Dependencies

For CLI-based consultants, you'll also need:

| Dependency | Required for | |------------|--------------| | Node.js 18+ | Gemini CLI, Codex CLI, Qwen CLI, MiniMax CLI | | Python 3.8+ | Mistral Vibe CLI |

# macOS
brew install node python

# Ubuntu/Debian
sudo apt-get install -y nodejs npm python3 python3-pip

# Verify
node --version && python3 --version

Verify All Prerequisites

Run the doctor command to check everything is installed:

./scripts/doctor.sh

Supported CLI Agents

AI Consultants follows the open Agent Skills standard, enabling cross-platform compatibility.

Claude Code

Status: ✅ Native support

Installation:

curl -fsSL https://raw.githubusercontent.com/matteoscurati/ai-consultants/main/scripts/install.sh | bash

Slash Commands:

| Command | Description | |---------|-------------| | /ai-consultants:consult | Main consultation - ask AI consultants a coding question | | /ai-consultants:help | Show all commands and usage |

Configuration (presets, strategies, features, personas, API keys) can be managed via natural language — just ask.

Self-Exclusion: Claude consultant is automatically excluded when invoked from Claude Code. The command also prevents Claude from being selected as the synthesis provider; Codex and every other enabled consultant remain eligible. Natural-language skill invocations execute the panel directly rather than merely suggesting the slash command.

Verify:

./scripts/doctor.sh

OpenAI Codex CLI

Status: ✅ Compatible

Installation:

git clone https://github.com/matteoscurati/ai-consultants.git ~/.codex/skills/ai-consultants
~/.codex/skills/ai-consultants/scripts/doctor.sh --fix

Commands:

Use the same slash commands as Claude Code. Codex CLI loads skills from ~/.codex/skills/.

Self-Exclusion: Codex consultant is automatically excluded when invoked from Codex CLI.

Verify:

~/.codex/skills/ai-consultants/scripts/doctor.sh

Gemini CLI

Status: ✅ Compatible

Installation:

git clone https://github.com/matteoscurati/ai-consultants.git ~/.gemini/skills/ai-consultants
~/.gemini/skills/ai-consultants/scripts/doctor.sh --fix

Commands:

Use the same slash commands as Claude Code. Gemini CLI loads skills from ~/.gemini/skills/.

Self-Exclusion: Gemini consultant is automatically excluded when invoked from Gemini CLI.

Verify:

~/.gemini/skills/ai-consultants/scripts/doctor.sh

Cursor / Copilot / Windsurf (via SkillPort)

Status: ✅ Via SkillPort

Installation:

# Install SkillPort if not already installed
npm install -g skillport

# Add AI Consultants skill
skillport add github.com/matteoscurati/ai-consultants

# Load skill in your agent
skillport show ai-consultants

Or clone and use the included installer:

git clone https://github.com/matteoscurati/ai-consultants.git
cd ai-consultants
./scripts/skillport-install.sh

Commands:

SkillPort translates skill commands to the native agent format.

Cursor remains a supported host through SkillPort; it is not itself a consultant in the panel.

Verify:

skillport status ai-consultants

Standalone Bash

Status: ✅ Direct execution

Installation:

git clone https://github.com/matteoscurati/ai-consultants.git
cd ai-consultants
./scripts/doctor.sh --fix
./bin/ai-consultants configure

Commands:

# Basic consultation
./scripts/consult_all.sh "How to optimize this function?" src/utils.py

# With preset
./scripts/consult_all.sh --preset balanced "Redis or Memcached?"

# Side-by-side instead of the coverage union
./scripts/consult_all.sh --strategy compare_only "Microservices vs monolith?"

# With smart routing
ENABLE_SMART_ROUTING=true ./scripts/consult_all.sh "Bug in auth code"

# Follow-up questions
./scripts/followup.sh "Can you elaborate on that point?"
./scripts/followup.sh -c Gemini "Show me code example"

Self-Exclusion: Set INVOKING_AGENT environment variable:

INVOKING_AGENT=claude ./scripts/consult_all.sh "Question"   # Claude excluded
INVOKING_AGENT=codex ./scripts/consult_all.sh "Question"    # Codex excluded
./scripts/consult_all.sh "Question"                          # No exclusion

Verify:

./scripts/doctor.sh

Consultants

CLI-Based Consultants

| Consultant | CLI | Persona | Focus | |------------|-----|---------|-------| | Google Gemini | agy | The Architect | Design patterns, scalability, enterprise | | OpenAI Codex | codex | The Pragmatist | Simplicity, quick wins, proven solutions | | Mistral Vibe | vibe | The Devil's Advocate | Problems, edge cases, vulnerabilities | | Kimi K3 | kimi | The Eastern Sage | Holistic, balanced perspectives | | Claude | claude | The Synthesizer | Big picture, synthesis, connecting ideas | | Qwen3 | qwen | The Analyst | Data-driven analysis | | Grok | grok | The Provocateur | Challenge conventions | | MiniMax | mmx | The Pragmatic Optimizer | Performance, efficiency, pragmatism |

Grok uses Grok Build with grok-4.6 in an isolated, tool-free sandbox. Prompts are passed through a private file rather than process arguments. It falls back to the xAI API only when the CLI is missing, cannot launch, or has no usable authentication and GROK_API_KEY is configured; post-launch request failures are surfaced without a silent API charge. Grok CLI OAuth defaults to concurrent shared mode: HOME, workspace, prompt, output, permissions, and agent state remain isolated per invocation, while processes share one runner-owned persistent GROK_HOME so the CLI's own auth lock can coordinate refresh. Credential adoption/publication uses a short lock and digest CAS, so an external grok login wins and the affected run fails without overwriting it or falling back to the API. Set GROK_OAUTH_MODE=serialized only for diagnostic full-run serialization. A new generation performs one locked inventory bootstrap because Grok 1.0.4 lazily initializes home metadata; inference is never serialized by that bootstrap. Qwen3 and MiniMax can also switch from their CLI to API transport. Gemini, Codex, Claude, and Mistral are CLI/API switchable. Gemini, Grok, and Kimi verify the requested model against the CLI inventory before dispatch when that inventory exists. Grok and Kimi compatibility is capability-probed before dispatch: the requested model, headless arguments, and structured-output surface must be available. Any CLI version is accepted when those checks pass; the observed version is response provenance only.

API-Only Consultants

| Consultant | Default Model | Persona | Focus | |------------|---------------|---------|-------| | GLM | glm-5.3-flash | The Methodologist | Structured approaches | | DeepSeek | deepseek-flash (V4.1 Flash) | The Code Specialist | Algorithms, code generation |

Installing Consultant CLIs

At least 2 consultant CLIs are required:

curl -fsSL https://antigravity.google/cli/install.sh | bash  # Gemini (Antigravity CLI: agy)
npm install -g @openai/codex           # Codex
pip install mistral-vibe               # Mistral

# Optional CLI-based consultants
curl -L code.kimi.com/install.sh | bash            # Kimi K3
npm install -g @qwen-code/qwen-code@latest  # Qwen (alternative to API)
curl -fsSL https://x.ai/cli/install.sh | bash # Grok Build (grok-4.6)
npm install -g mmx-cli                       # MiniMax

Kimi is pinned to K3 for every consultation, even if the user's Kimi CLI has a different default model:

KIMI_MODEL=kimi-code/k3 ai-consultants \
  "Review this API design from a holistic perspective"

Quality Tiers

Choose the right balance of quality, speed, and cost with model quality tiers.

Tier Presets

| Preset | Tier | Agents | Use Case | |--------|------|--------|----------| | max_quality | Maximum + max effort | All 10 | Critical decisions | | medium | Standard | 3 | General questions | | fast | Economy | 2 | Quick checks |

A preset only chooses the consultant set and model tier — every run then fans out in parallel and returns the coverage union. Preset panels use statically configured transports only (a CLI on PATH, or selected API mode with its key). Host self-exclusion is fail-closed; lost canonical slots are filled from ALL_CONSULTANTS in canonical order. If the effective target cannot be met, including after an enabled health gate prunes the panel, the run stops with promised/selected/missing-capacity guidance. Configured custom API agents are appended and may satisfy capacity, so a full preset can exceed its advertised count. max_quality still advertises 10 consultants, with an effective target of 9 for a canonical invoking host. For max_quality, Grok, GLM, and DeepSeek are also pinned to their highest accepted reasoning effort: Grok Build uses xhigh, while GLM and DeepSeek use max. Unsupported transport capabilities fail explicitly instead of reducing effort silently.

The maximum preset also applies the transport budgets proven by the live panel smoke: four bounded advisory turns for Mistral/Grok, a 600-second Token Plan window for Qwen3.8-Max, a 600-second DeepSeek reasoning window, and larger OpenAI-compatible output budgets for Qwen, GLM, and DeepSeek. MiniMax M3 likewise receives a 16,384-token completion budget in the maximum tier and a provider-specific compact Markdown contract through mmx's native system channel. Provider output is tagged structured, fallback, or error; malformed/truncated JSON fails closed. In coverage/union mode, only locally atomized summary, pros, cons, alternatives, caveats, and references can be source-attributed; fallback prose remains context-only for manual review. synthesis.json records coverage_integrity: MET applies only to those audited fields, while DEGRADED/FAILED must not be read as comprehensive coverage. It also records locally authoritative coverage_input_truncated and truncated_consultants: only non-normalizable fallback context is capped (at Unicode code-point boundaries), never atomic findings; a truncated coverage input is disclosed and cannot support a comprehensive coverage claim.

Models by Tier

| Consultant | max_quality | Premium | Standard | Economy | |------------|---------------|---------|----------|---------| | Claude | claude-fable-5-1 | claude-fable-5-1 | claude-opus-5 | claude-haiku-4-5 | | Gemini CLI | Gemini 3.7 Flash (High) | Gemini 3.7 Flash (High) | Gemini 3.7 Flash (High) | Gemini 3.7 Flash (Low) | | Gemini API | gemini-3.1-pro-preview | gemini-3.1-pro-preview | gemini-3.1-pro-preview | gemini-3.1-pro-preview | | Codex | gpt-6-astra | gpt-6-astra | gpt-5.6-terra | gpt-5.6-luna | | Mistral CLI | mistral-medium-3.5 | mistral-medium-3.5 | mistral-medium-3.5 | devstral-small-2 | | Mistral API | mistral-large-3 | mistral-large-3 | mistral-large-3 | mistral-large-3 | | DeepSeek | deepseek-flash | deepseek-flash | deepseek-flash | deepseek-flash | | GLM | glm-5.3-flash | glm-5.3-flash | glm-5.3-flash | glm-4-flash | | Grok | grok-4.6 | grok-4.6 | grok-4.5 | grok-4.5 | | Qwen3 | qwen3.8-max when Token Plan is configured; otherwise qwen3.7-max | qwen3.7-max | qwen3.6-35b-a3b | qwen3-32b | | Kimi | kimi-code/k3-256k | kimi-code/k3 | kimi-code/k3 | kimi-code/k3 | | MiniMax | MiniMax-M3 | MiniMax-M2.7 | MiniMax-M2.7 | MiniMax-M2.5 |

Promotion is transport-specific. Gemini 3.7 Flash High completed an exact live smoke through the agy adapter and is now the CLI default; Low is the CLI economy target. The Google API model remains gemini-3.1-pro-preview, while gemini-3.7-flash stays an API-only opt-in until that separate transport is verified. The new Mistral API IDs (mistral-medium-3-5, mistral-large-2512, mistral-small-2603) remain catalogued opt-ins. Claude Fable 5.1 is the default/premium/maximum target; use CLAUDE_MODEL=claude-opus-5 for the lower-cost standard override. Selecting a preset later intentionally reapplies that preset's tier and can replace an explicit model override for the run. Qwen3.8-Max is likewise selected by max_quality only when API mode already points at an authenticated OpenAI-compatible Token Plan /chat/completions endpoint; the preset never repoints a DashScope key or CLI installation.

Usage

Claude Code:

/ai-consultants:consult --preset max_quality "critical architecture decision"
/ai-consultants:consult --preset fast "quick syntax question"

Bash:

./scripts/consult_all.sh --preset max_quality "microservices vs monolith?"
./scripts/consult_all.sh --preset fast "how to use async/await?"

# Programmatic tier selection
source scripts/config.sh
apply_model_tier "premium"   # Set all to premium models
apply_model_tier "maximum"   # max_quality-only / separate-plan models
apply_model_tier "economy"   # Set all to economy models

Configuration

Public Modes

| Mode | Preset | Default strategy | Use case | |---|---|---|---| | fast-check | fast | coverage | Fast economy panel for a quick coverage check | | coverage-review | balanced | coverage | Balanced panel for a general coverage review | | max-coverage | max_quality | coverage | Maximum-quality panel for the broadest coverage |

Configuration Presets

| Preset | Alias | Target | Tier | Use case | |---|---|---:|---|---| | minimal | — | 2 | base | Quick questions | | balanced | — | 3 | base | Standard coverage | | thorough | — | 3 | base | Comprehensive analysis | | high-stakes | — | 4 | premium | Critical decisions | | security | — | 3 | base | Security reviews | | cost-capped | — | 3 | economy | Budget-conscious options | | max_quality | max-quality | 10 | maximum | Maximum coverage for critical decisions | | medium | — | 3 | standard | General questions | | fast | — | 2 | economy | Quick checks |

Synthesis Strategies

| Strategy | Description | |---|---| | coverage | Union of every distinct point across the panel Default | | compare_only | Present each consultant side-by-side, without a synthesized union | | majority | Produce one blended recommendation, weighting all equally | | risk_averse | Weight conservative responses higher | | security_first | Prioritize security-focused insights | | cost_capped | Prefer cheaper consultant opinions within budget |

Bash:

./scripts/consult_all.sh --preset balanced "Question"

Bash:

./scripts/consult_all.sh --strategy risk_averse "Question"

Environment Variables

Automatic configuration (recommended):

# Detect installed CLIs and available API keys, then write the persistent config
ai-consultants configure

# Review the consultant selection and transports interactively
ai-consultants configure --interactive

# Set any persistent parameter without opening an editor
ai-consultants configure \
  --set DEFAULT_PRESET=balanced \
  --set DEFAULT_STRATEGY=coverage \
  --set ENABLE_SMART_ROUTING=true

# Inspect the complete machine-readable parameter surface
ai-consultants configure --show-parameters

The configurator covers every persistent setting in scripts/config.sh, plus credentials, persona overrides, transport controls, advanced context knobs, and calibration commands. Existing custom values and secrets are preserved, while ENABLE_* flags are refreshed from detected availability (and can be pinned with --set). Rewrites create a private timestamped backup. Use --advanced to review every parameter or --dry-run to preview a redacted result. Auto-selected *_USE_API values are marked # ai-consultants:auto, allowing a later run to adapt when a CLI or credential changes. Environment variables, --set, and unmarked values remain explicit user choices, except for the exact historical generated Claude default described below. Managed model defaults use # ai-consultants:default; configure upgrades un-pinned historical CLAUDE_MODEL=claude-opus-4-8 and claude-opus-5 defaults to Fable 5.1, along with the exact managed Gemini CLI, GLM, and Grok defaults. To keep the lower-cost Opus 5 choice, run ai-consultants configure --set CLAUDE_MODEL=claude-opus-5; explicit model overrides are stored with # ai-consultants:pin.

Enter credentials through --interactive/--advanced or export them before the run; avoid passing API keys through --set, where the shell may retain them in history or expose them in the process list.

For a manual starter template instead, run ai-consultants init and edit ~/.config/ai-consultants/.env.

For ad-hoc overrides without persisting, the most common knobs:

DEFAULT_PRESET=balanced      # minimal | balanced | thorough | high-stakes | fast | security
DEFAULT_STRATEGY=coverage    # coverage | compare_only | majority | risk_averse | security_first | cost_capped
ENABLE_SMART_ROUTING=true    # Auto-select consultants by question category
MAX_SESSION_COST=1.00        # USD budget cap (paired with ENABLE_BUDGET_LIMIT=true to enforce)
KIMI_MODEL=kimi-code/k3      # Pin the Kimi consultant to K3
CLAUDE_API_MAX_TOKENS=16384  # Shared thinking + visible-output budget in API mode
MISTRAL_CLI_MODEL=mistral-medium-3.5 # Vibe alias; MISTRAL_MODEL remains API-only
GEMINI_MODEL="Gemini 3.7 Flash (High)" # agy CLI; API uses GEMINI_API_MODEL

Full reference: references/configuration.md. Copy-paste workflows: docs/RECIPES.md. For category-aware preset suggestions: ai-consultants doctor --suggest-preset --question "...".

Configuration Recipes

Breadth review — the coverage union (default):

ai-consultants --preset high-stakes \
  "What could go wrong with this webhook-delivery design?" src/webhooks.ts@PRIMARY

Security review, security-first framing:

ai-consultants --preset security --strategy security_first \
  "Find authentication bypasses" src/auth.ts@PRIMARY

Side-by-side comparison (no synthesized union):

ai-consultants --strategy compare_only \
  "Event log or mutable relational state for this service?"

Live health gate plus hard quorum:

ENABLE_HEALTH_GATE=true \
QUORUM_MIN=3 \
QUORUM_ACTION=stop \
ai-consultants "Make a release recommendation"

See the recipes for balanced, fast, security, compare-only, budget-capped, CLI-only, hybrid API, and large-context workflows.

Doctor Command

Diagnose, suggest, and fix:

ai-consultants doctor                                          # Installation and configuration checks
ai-consultants doctor --fix                                    # Auto-fix common issues
ai-consultants doctor --json                                   # JSON for automation
ai-consultants doctor --live                                   # Real ping per consultant — catches installed-but-unauthenticated CLIs
ai-consultants doctor --suggest-config                         # Print recommended ENABLE_* based on detected CLIs
ai-consultants doctor --suggest-preset --question "..."        # Recommend preset + strategy for a question
ai-consultants update-clis                                     # Check & update every installed consultant CLI
ai-consultants update-clis --dry-run                           # Preview: each CLI's install method + update command

When a consultant fails mid-consultation, the run surfaces the captured reason (e.g. CLI not found, 401 Unauthorized) instead of a bare "Failed", so you can tell not installed from not authenticated from transient.

How It Works

Classify -> Route -> Fan out (parallel) -> Coverage synthesis
   |          |            |                      |
 category  smart       Gemini (8)          union of every
          routing      Codex (7)           distinct point,
                       Mistral (6)         deduplicated
                       Kimi (7)

1. Classify the question into a category.
2. Route (optional, ENABLE_SMART_ROUTING) to the consultants with the best category affinity (references/affinity.json).
3. Fan out to every selected consultant in parallel — one shot each, no serial rounds.
4. Synthesize the coverage union over auditable normalized fields. Read coverage_integrity before treating it as complete: MET means every local atomic source ID is represented once; DEGRADED and FAILED are explicitly non-comprehensive. Override with --strategy compare_only (side-by-side) or majority (a single blended recommendation).

Output

Each consultation generates:

${XDG_CACHE_HOME:-$HOME/.cache}/ai-consultants/consultations/TIMESTAMP/
├── context.md            # Built consultation context
├── gemini.json          # Individual responses
├── codex.json           #   with confidence scores
├── mistral.json
├── grok.json
├── synthesis.json       # Coverage union plus coverage_integrity/audited_fields
├── optimization_metrics.json
└── report.md            # Human-readable report

The command prints the exact output directory as its final stdout line.

Best Practices

When the Panel Helps Most

The panel's edge is coverage — surfacing what a single model misses. It pays off on open-ended, breadth questions:

• Threat-modeling and design review ("what could go wrong with this?")
• Enumerating risks, edge cases, or failure modes
• "What am I missing?" / exhaustive audits
• Decisions that are difficult to reverse

For a single-answer factual or defect-finding question, a single strong model is usually enough — the panel adds little.

Interpreting Results

| Scenario | Recommendation | |----------|----------------| | A point only one consultant raised | Weigh it — the diversity is the point | | Mistral (Devil's Advocate) flags a risk | Investigate it | | Consultants diverge on approach | Use --strategy compare_only to see each side-by-side |

Security

• Never include credentials or API keys in queries
• Review and redact sensitive code before sending it to any external consultant
• Private query and context-staging files are removed automatically; generated reports remain in the XDG cache directory until you remove them

Documentation

• Setup Guide - Installation, authentication, Claude Code setup
• Configuration Recipes - Copy-paste workflows for routing, budgets, synthesis, and transport
• Cost Rates - Model pricing and budgets
• Smart Routing - Category-based routing
• JSON Schema - Output format specification
• Reference Details - Presets, strategies, best practices
• Changelog - Complete version history
• Contributing - How to contribute

License

MIT License - see LICENSE for details.

Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.