claude-council

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
• 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

# Clone to your plugins directory
git clone https://github.com/hex/claude-council.git
claude --plugin-dir /path/to/claude-council

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

Quick Reference

Flag	Description
--providers=list	Query specific providers (e.g., gemini,openai,codex)
--roles=list	Assign roles (e.g., security,performance or preset like balanced)
--debate	Enable two-round debate mode
--file=path	Include specific file in context
--output=path	Export response to markdown file
--quiet	Show only synthesis, hide individual responses
--agents	Agent-enhanced analysis with subagents (slower, deeper)
--no-cache	Force fresh queries, skip cache
--no-auto-context	Disable automatic file detection
--no-pane	Disable streaming tmux pane (default: on inside tmux)
--verbosity=LEVEL	Response style: brief / standard / detailed

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"