small-council

name	small-council
description	Consult the Small Council - a multi-LLM deliberation system that gathers independent answers from multiple frontier AI models, has them anonymously rank each other's responses, then synthesizes a consensus answer. Use for complex coding questions, architectural decisions, code reviews, debugging challenges, or when you want multiple expert perspectives. Trigger with "small council", "ask the council", "consult the council", "get a second opinion", or "what do other models think".
license	MIT
compatibility	Requires macOS or Linux, Python 3.10+, tmux, uv or pipx, and OPENROUTER_API_KEY with OpenRouter credits.
metadata	{"author":"Eytan Levit","version":"0.1.0","repo":"https://github.com/eytanlevit/small-council"}
allowed-tools	Task Bash Read Grep Glob

Small Council Consultation

Get expert guidance on coding questions through multi-LLM deliberation.

How It Works

The Small Council uses a 3-stage deliberation process:

1. Stage 1: 4 frontier LLMs (GPT-5.4, GPT-5.4-Pro, Gemini 3.1 Pro, Claude Opus 4.6) independently answer your question
2. Stage 2: Each model anonymously ranks all responses
3. Stage 3: Claude Opus 4.6 as chairman synthesizes the final consensus answer

This approach leverages the collective intelligence of multiple AI models, ensuring well-rounded, thoroughly-vetted answers.

When to Use Small Council

The Small Council is ideal for:

• Architectural decisions: "Should we use microservices or a monolith?"
• Code reviews: "Review this implementation for bugs and improvements"
• Complex debugging: Multi-model analysis of tricky bugs
• Design patterns: "What pattern best fits this use case?"
• Performance optimization: Get diverse optimization strategies
• Best practices: "What's the recommended approach for X?"

Not for simple questions - use when you want multiple expert perspectives synthesized.

Prerequisites

• OPENROUTER_API_KEY environment variable set
• Small Council CLI installed: uv tool install small-council (or uv tool install git+https://github.com/eytanlevit/small-council)
• tmux installed

Process

0. Ensure Dependencies (First Use)

command -v small-council || bash ~/.claude/skills/small-council/scripts/setup.sh

If setup reports issues, help the user resolve them before proceeding.

1. Think Deeply About the Question

This step is critical. The quality of the prompt determines the quality of the deliberation.

Before proceeding, consider:

• What specifically are we trying to figure out?
• What makes this problem worthy of multi-model deliberation?
• What context do the models need?
• What would a genuinely helpful response look like?

Formulate a clear, comprehensive question that:

• Explains the core problem or decision
• Provides relevant background and constraints
• States what you've already tried (for bugs)
• Asks for specific insights or guidance

Examples of well-crafted prompts:

Bad: "How do I fix authentication?"

Good: "We're getting intermittent 401 errors on token refresh after deploying the new JWT middleware. Tokens validate correctly in unit tests but fail in production under load. The error only occurs for about 5% of requests. What could cause this discrepancy between test and production behavior?"

Bad: "Should I use microservices?"

Good: "We're deciding whether to split our monolithic API into microservices. Current system: 50k daily active users, 10-person team, deploying 3x/week. Main pain points: shared database bottlenecks, long CI times. Constraints: can't hire more DevOps, need to maintain current deployment velocity. What are the trade-offs and which approach fits our situation better?"

2. Identify Relevant Context Files

Based on the question, determine what code/files the council needs to analyze.

Use the Explore agent to find relevant files:

Task(
  subagent_type=Explore,
  prompt="Find files related to [specific area from your prompt]",
  thoroughness="medium"
)

Extract the file paths from the Explore agent's response. This context is crucial for quality deliberation.

3. Show What Will Be Sent

Display to user:

• The comprehensive prompt you crafted
• List of files to include
• Brief message: "Consulting the Small Council..."

4. Execute Small Council (Tmux-Based)

IMPORTANT: Always use the tmux-based approach. This ensures the council process survives even if Claude's session gets killed (common in non-interactive/batch mode).

Step 4a: Start Council in Tmux

small-council tmux start \
  -p "Your comprehensive prompt here" \
  -f "file1.ts" -f "file2.ts"

This outputs JSON with session info:

{
  "session": "council-1234567890-12345",
  "output": "/tmp/council-1234567890-12345.out",
  "done": "/tmp/council-1234567890-12345.done"
}

Capture the session ID from this output!

Step 4b: Wait for Completion (Long Timeout)

Bash(
  command: "small-council tmux wait 'council-SESSIONID' --timeout 3600 --poll-interval 30",
  timeout: 600000,
  description: "Waiting for Small Council response"
)

The council typically takes 5-15 minutes. The --timeout 3600 tells the CLI to poll for up to 1 hour (matching the LLM timeout). The Bash tool timeout (600000ms / 10 min) may fire first — if so, just call the same command again to continue waiting. Repeat until complete.

Step 4c: Check Status (Quick, Non-Blocking)

If you need to check without waiting:

small-council tmux status "council-SESSIONID"

Or list all sessions:

small-council tmux status --list

Resuming After Context Refresh

If Claude's context was refreshed mid-wait:

1. List existing sessions:

   small-council tmux status --list
   

2. Check/wait for the session:

   small-council tmux wait "council-SESSIONID" --timeout 600 --poll-interval 30
   

3. If completed, the output file persists at /tmp/council-SESSIONID.out

5. Present the Council's Wisdom

When the council responds:

• Summarize the key consensus findings
• Highlight any dissenting opinions or trade-offs mentioned
• Extract actionable recommendations
• Note any follow-up questions to explore
• If relevant, mention which aspects had strong agreement vs. varied perspectives