Claude Concilium

Multi-agent AI consultation framework for Claude Code via MCP.

Get a second (and third) opinion from other LLMs when Claude Code alone isn't enough.

hljs language-css

Claude Code ──┬── OpenAI (Codex CLI) ──► Opinion A
              ├── Gemini (gemini-cli) ─► Opinion B
              │
              └── Synthesis ◄── Consensus or iterate

The Problem

Claude Code is powerful, but one brain can miss bugs, overlook edge cases, or get stuck in a local optimum. Critical decisions benefit from diverse perspectives.

The Solution

Concilium runs parallel consultations with multiple LLMs through standard MCP protocol. Each LLM server wraps a CLI tool — no API keys needed for the primary providers (they use OAuth).

Key features:

Parallel consultation with 2+ AI agents
Production-grade fallback chains with error detection
Each MCP server works standalone or as part of Concilium
Plug & play: clone, npm install, add to .mcp.json

Architecture

hljs language-scss

┌─────────────────────────────────────────────────────────┐
│                     Claude Code                          │
│                                                          │
│  "Review this code for race conditions"                  │
│                                                          │
│  ┌──────────────┐  ┌──────────────┐                      │
│  │  MCP Call #1  │  │  MCP Call #2  │   (parallel)        │
│  └──────┬───────┘  └──────┬───────┘                      │
│         │                  │                              │
└─────────┼──────────────────┼──────────────────────────────┘
          │                  │
          ▼                  ▼
   ┌──────────────┐   ┌──────────────┐
   │  mcp-openai  │   │  mcp-gemini  │     Primary agents
   │  (codex exec)│   │ (gemini -p)  │
   └──────┬───────┘   └──────┬───────┘
          │                  │
          ▼                  ▼
   ┌──────────────┐   ┌──────────────┐
   │   OpenAI     │   │   Google     │     LLM providers
   │   (OAuth)    │   │   (OAuth)    │
   └──────────────┘   └──────────────┘

   Fallback chain (on quota/error):
   OpenAI → Qwen → DeepSeek
   Gemini → Qwen → DeepSeek

Quickstart

1. Clone and install

hljs language-bash

git clone https://github.com/spyrae/claude-concilium.git
cd claude-concilium

# Install dependencies for each server
cd servers/mcp-openai && npm install && cd ../..
cd servers/mcp-gemini && npm install && cd ../..
cd servers/mcp-qwen && npm install && cd ../..

# Verify all servers work (no CLI tools required)
node test/smoke-test.mjs

Expected output:

hljs language-less

PASS mcp-openai  (Tools: openai_chat, openai_review)
PASS mcp-gemini  (Tools: gemini_chat, gemini_analyze)
PASS mcp-qwen    (Tools: qwen_chat)
All tests passed.

2. Set up providers

Pick at least 2 providers:

Provider	Auth	Free Tier	Setup
OpenAI	`codex login` (OAuth)	ChatGPT Plus weekly credits	Setup guide
Gemini	Google OAuth	1000 req/day	Setup guide
Qwen	OAuth or API key	Varies	Setup guide
DeepSeek	API key	Pay-per-use (cheap)	Setup guide

3. Add to Claude Code

Copy config/mcp.json.example and update paths:

hljs language-bash

# Edit the example with your actual paths
cp config/mcp.json.example .mcp.json
# Update "/path/to/claude-concilium" with actual path

Or add servers individually to your existing .mcp.json:

hljs language-json

{
  "mcpServers": {
    "mcp-openai": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/servers/mcp-openai/server.js"],
      "env": {
        "CODEX_HOME": "~/.codex-minimal"
      }
    },
    "mcp-gemini": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/servers/mcp-gemini/server.js"]
    }
  }
}

4. Install the skill (optional)

Copy the Concilium skill to your Claude Code commands:

hljs language-bash

cp skill/ai-concilium.md ~/.claude/commands/ai-concilium.md

Now use /ai-concilium in Claude Code to trigger a multi-agent consultation.

MCP Servers

Each server can be used independently — you don't need all of them.

Server	CLI Tool	Auth	Tools
mcp-openai	`codex`	OAuth (ChatGPT Plus)	`openai_chat`, `openai_review`
mcp-gemini	`gemini`	Google OAuth	`gemini_chat`, `gemini_analyze`
mcp-qwen	`qwen`	OAuth / API key	`qwen_chat`

DeepSeek uses the existing deepseek-mcp-server npm package — no custom server needed.

How It Works

Consultation Flow

Formulate — describe the problem concisely (under 500 chars)
Send in parallel — OpenAI + Gemini get the same prompt
Handle errors — if a provider fails, fallback chain kicks in (Qwen → DeepSeek)
Synthesize — compare responses, find consensus
Iterate (optional) — resolve disagreements with follow-up questions
Decide — apply the synthesized solution

Error Detection

All servers detect provider-specific errors and return structured responses:

Error Type	Meaning	Action
`QUOTA_EXCEEDED`	Rate/credit limit hit	Use fallback provider
`AUTH_EXPIRED` / `AUTH_REQUIRED`	Token needs refresh	Re-authenticate CLI
`AUTH_NOT_CONFIGURED`	Qwen auth type not set	Set `QWEN_AUTH_TYPE` env var
`MODEL_NOT_SUPPORTED`	Model unavailable on plan	Use default model
Timeout	Process hung	Auto-killed, use fallback

Fallback Chain

hljs language-yaml

Primary:   OpenAI ──────────────► Response
           (QUOTA_EXCEEDED?)
                    │
Fallback 1: Qwen ──┴────────────► Response
           (timeout?)
                    │
Fallback 2: DeepSeek ───────────► Response (always available)

When to Use Concilium

Scenario	Recommended Agents
Code review	OpenAI + Gemini (parallel)
Architecture decision	OpenAI + Gemini → iterate if disagree
Stuck bug (3+ attempts)	All available agents
Performance optimization	Gemini (1M context) + OpenAI
Security review	OpenAI + Gemini + manual verification

Docker

Run any server in a container:

hljs language-bash

# Build
docker build -t claude-concilium .

# Run a specific server (mcp-openai | mcp-gemini | mcp-qwen)
docker run -i --rm -e SERVER=mcp-openai claude-concilium
docker run -i --rm -e SERVER=mcp-gemini claude-concilium

Note: The servers wrap CLI tools (codex, gemini, qwen) that require local authentication. Mount your auth credentials when running:

hljs language-bash

# OpenAI (Codex)
docker run -i --rm -e SERVER=mcp-openai \
  -v ~/.codex:/root/.codex:ro \
  claude-concilium

# Gemini
docker run -i --rm -e SERVER=mcp-gemini \
  -v ~/.config/gemini:/root/.config/gemini:ro \
  claude-concilium

Customization

See docs/customization.md for:

Adding your own LLM provider
Modifying the fallback chain
MCP server template
Custom prompt strategies

Documentation

Architecture — flow diagrams, error handling, design decisions
OpenAI Setup — Codex CLI, ChatGPT Plus, minimal config
Gemini Setup — gemini-cli, Google OAuth
Qwen Setup — Qwen CLI, DashScope
DeepSeek Setup — API key, npm package
Customization — add your own LLM, modify chains

Changelog

v2.0.0 (2026-03-02)

mcp-qwen:

Prompt delivery via stdin (-p -) instead of command argument — safe for any content, no length limits
OAuth auth-type support via QWEN_AUTH_TYPE env var (e.g., qwen-oauth)
New error detection: AUTH_NOT_CONFIGURED (catches "no auth type is selected")
Graceful shutdown handler (SIGTERM)

mcp-openai:

Default timeout increased from 90s to 180s (codex exec can be slow on complex prompts)

All servers:

Version bumped to 2.0.0
Updated documentation and setup guides

v0.1.0 (2025-12-15)

Initial release with 3 MCP servers (OpenAI, Gemini, Qwen)
Concilium skill with fallback chains
Smoke test suite
Docker support

License

MIT

claude-concilium

Claude Concilium

The Problem

The Solution

Architecture

Quickstart

1. Clone and install

2. Set up providers

3. Add to Claude Code

4. Install the skill (optional)

MCP Servers

How It Works

Consultation Flow

Error Detection

Fallback Chain

When to Use Concilium

Docker

Customization

Documentation

Changelog

v2.0.0 (2026-03-02)

v0.1.0 (2025-12-15)

License

Similar Packages

Repository

Tags

Original Author

Publisher

Repository