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