claude-council

A Claude Code plugin that consults multiple AI coding agents in parallel and shows you their answers side-by-side. Useful when one model's bias could mislead you and the right call depends on cross-checking — architecture decisions, debugging dead ends, security reviews, framework picks.

Quick start · Usage · Configuration · Reference · Development

Quick start

# 1. Install via Claude Code plugin marketplace
/plugin marketplace add hex/claude-marketplace
/plugin install claude-council

# 2. Configure at least one provider — any of these works:
export OPENAI_API_KEY="..."         # or GEMINI_API_KEY, XAI_API_KEY, PERPLEXITY_API_KEY
                                    # OR install the codex / gemini CLIs (uses your existing
                                    # subscription — no API key needed)

# 3. Ask anything
/claude-council:ask "Should I use UUID or BIGINT primary keys for a SaaS users table?"

You get side-by-side responses from each configured provider:

🔳 Codex - gpt-5.5
   Use UUID primary keys — they avoid enumeration, work across distributed
   services, and survive imports/exports cleanly.

🟦 Gemini-cli - gemini-3-flash-preview
   UUIDv7 specifically: security of non-guessable IDs plus the index
   locality of time-ordered sequences.

🟥 Grok - grok-4.20-reasoning
   BIGINT autoincrement — smaller index, faster joins. Handle public-
   exposure concerns with a separate UUID slug column.

🟩 Perplexity - sonar-reasoning-pro
   BIGINT: 25% smaller than UUID, better cache locality, with citations
   to Postgres benchmarks.

## Synthesis
Two providers prefer UUID(v7), two prefer BIGINT. Choice depends on
whether you need distributed ID generation.

Inside tmux, results stream into a side pane in real time with vendor-colored banners. Run /claude-council:status to confirm what's configured and connected.

Features

• Query Gemini, OpenAI (GPT/Codex), Grok, and Perplexity simultaneously
• Use the codex and gemini CLIs (subscription auth) when installed — preferred over their API siblings
• Side-by-side comparison of responses with vendor-colored headers
• Streaming tmux pane that renders responses as they land
• Specialized roles, debate mode, and agent-enhanced deep analysis for high-stakes decisions
• Background jobs (--async) for long-running queries, with /claude-council:result to fetch, list, and cancel
• Opt-in stop-gate: a second model reviews your uncommitted diff before Claude ends its turn
• Extensible provider system — add new AI agents easily
• Proactive agent that suggests consulting the council on architecture / debugging dead ends

Installation

From Marketplace (Recommended)

# Add the hex-plugins marketplace
/plugin marketplace add hex/claude-marketplace

# Install claude-council
/plugin install claude-council

Direct from GitHub

/plugin install hex/claude-council

Manual (run from a local clone)

For normal use, prefer the marketplace or GitHub install above — both persist across sessions. A manual clone is for running from a local working copy (development, or offline). Clone the repo anywhere, then point Claude Code at the repo root for the current session:

git clone https://github.com/hex/claude-council.git
claude --plugin-dir /path/to/claude-council    # repo root; loaded for this session only

Cloned it and nothing loads? Two traps to avoid:

1. Don't clone into ~/.claude/plugins/ (Windows: %USERPROFILE%\.claude\plugins\). That's Claude Code's managed install cache — it is never scanned for manually-added plugins, so the plugin won't appear in the Installed tab or respond to its slash commands.
2. pluginDirectories in settings.json does nothing — it isn't a real setting, so it's silently ignored (no error shown). Use --plugin-dir above for a local clone, or install via the marketplace / GitHub for a persistent setup.

Usage

Slash Commands

# Query all configured providers
/claude-council:ask "How should I structure authentication in this Express app?"

# Query specific providers
/claude-council:ask --providers=gemini,openai "What's the best approach for caching here?"

# Include a specific file for review
/claude-council:ask --file=src/auth.ts "What's wrong with this implementation?"

# Export response to markdown file
/claude-council:ask --output=docs/auth-decision.md "How should we implement authentication?"

# Quiet mode - show only synthesis
/claude-council:ask --quiet "What's the best caching strategy?"

# Check connectivity and configured models for each provider
/claude-council:status

# Run a long query in the background, fetch it later
/claude-council:ask --async "Deep-dive the tradeoffs of event sourcing here"
/claude-council:result <job-id>

Quick Reference

Specialized Roles

Assign different perspectives to each provider for more comprehensive reviews:

# Use specific roles
/claude-council:ask --roles=security,performance,maintainability "Review this auth code"

# Use a preset
/claude-council:ask --roles=balanced "Review this implementation"

Available roles:

• security - Security Auditor (vulnerabilities, OWASP Top 10)
• performance - Performance Optimizer (efficiency, bottlenecks)
• maintainability - Maintainability Advocate (clarity, future changes)
• devil - Devil's Advocate (challenges assumptions)
• simplicity - Simplicity Champion (identifies over-engineering)
• scalability - Scalability Architect (growth, scaling)
• dx - Developer Experience (API ergonomics)
• compliance - Compliance Officer (GDPR, regulations)

Presets:

• balanced - security, performance, maintainability
• security-focused - security, devil, compliance
• architecture - scalability, maintainability, simplicity
• review - security, maintainability, dx

Roles are assigned to providers in order, ensuring each provider approaches the question from a different angle.

Debate Mode

Enable multi-round discussions where providers critique each other:

/claude-council:ask --debate "How should I structure the database schema?"

How it works:

1. Round 1: All providers answer the question normally
2. Round 2: Each provider sees the others' responses and provides rebuttals
3. Synthesis: Incorporates debate insights, consensus shifts, and unresolved tensions

Debate mode surfaces blind spots and stress-tests recommendations. The synthesis includes:

• Strongest criticisms raised
• Where providers changed positions after seeing alternatives
• Genuine disagreements that remain

Combine with roles for focused debates:

/claude-council:ask --debate --roles=security,performance,simplicity "Review this architecture"

Agent-Enhanced Analysis (--agents)

For complex decisions where deeper analysis justifies the extra time and cost, --agents spawns parallel Claude subagents that each independently query, evaluate, and analyze their provider's response before the orchestrator synthesizes everything.

# Explicit flag
/claude-council:ask --agents "Should we migrate from REST to GraphQL? What are the tradeoffs?"

# Combine with other flags
/claude-council:ask --agents --roles=security,scalability --providers=gemini,openai "Review this auth architecture"

What each subagent does (beyond a simple API call):

1. Queries the provider
2. Evaluates response quality - did it actually address the question?
3. If the response is vague or off-topic, reformulates and retries
4. Asks follow-up questions to surface deeper insights
5. Extracts structured analysis: key recommendations, confidence level, blind spots

Enhanced synthesis includes:

• Confidence-weighted consensus (high-confidence agreement weighted more)
• Cross-provider blind spot analysis
• Divergence with context (why providers disagree)

Natural language triggers: The command also detects complex questions automatically. If your question contains architecture, security review, tradeoff analysis, or similar signals, you'll be asked whether to enable agent mode.

Cost and performance implications: Agent mode spawns one Claude subagent per provider. This means ~4x more Claude API usage and ~15-25 seconds additional latency compared to standard mode. Use it for high-stakes decisions, not quick questions.

Local Council (--local)

If you have no provider keys and no codex / gemini CLI installed, you can still convene a council — locally, using Claude alone:

# Explicit
/claude-coun