spyrae/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.
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
Quickstart
1. Clone and install
Expected output:
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:
Or add servers individually to your existing .mcp.json:
4. Install the skill (optional)
Copy the Concilium skill to your Claude Code commands:
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
1. **Formulate** — describe the problem concisely (under 500 chars)
2. **Send in parallel** — OpenAI + Gemini get the same prompt
3. **Handle errors** — if a provider fails, fallback chain kicks in (Qwen → DeepSeek)
4. **Synthesize** — compare responses, find consensus
5. **Iterate** (optional) — resolve disagreements with follow-up questions
6. **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
When to Use Concilium
| Scenario | Recommended Agents |
|----------|-------------------|
| Code review | OpenAI + Gemini (parallel) |