LLM Council Skill
Multi-LLM deliberation orchestrator. Implements a 3-stage council process:
Stage 1 (parallel independent responses) -> Stage 2 (anonymized peer review with ranking) ->
Stage 3 (chairman synthesis). Uses omega CLI wrapper skills for model invocation.
No server required -- pure Bash-level orchestration.
- Parallel dispatch to multiple LLM CLIs (Gemini, Codex, Cursor, Claude)
- Dynamic availability detection (only dispatches to available CLIs)
- 3-stage council protocol:
- Stage 1: Independent parallel responses
- Stage 2: Anonymized peer review with FINAL RANKING
- Stage 3: Chairman synthesis of all inputs
- Anonymized labeling (Response A, B, C...) to prevent model identity bias
- Configurable chairman model (default: current Claude session)
- Per-model timeout enforcement
- Graceful degradation (skips unavailable models)
- Structured output with all 3 stages preserved
Council Protocol
Stage 1: Independent Responses
Dispatch the user's prompt to all available omega CLIs in parallel:
node .claude/skills/omega-gemini-cli/scripts/verify-setup.mjs && HAS_GEMINI=1
node .claude/skills/omega-codex-cli/scripts/verify-setup.mjs && HAS_CODEX=1
node .claude/skills/omega-claude-cli/scripts/verify-setup.mjs && HAS_CLAUDE_CLI=1
node .claude/skills/omega-cursor-cli/scripts/verify-setup.mjs && HAS_CURSOR=1
TMPDIR=$(mktemp -d)
[ "$HAS_GEMINI" = "1" ] && node .claude/skills/omega-gemini-cli/scripts/ask-gemini.mjs "$PROMPT" --timeout-ms 120000 > "$TMPDIR/gemini.txt" 2>"$TMPDIR/gemini.err" &
[ "$HAS_CODEX" = "1" ] && node .claude/skills/omega-codex-cli/scripts/ask-codex.mjs "$PROMPT" --timeout-ms 120000 > "$TMPDIR/codex.txt" 2>"$TMPDIR/codex.err" &
[ "$HAS_CLAUDE_CLI" = "1" ] && node .claude/skills/omega-claude-cli/scripts/ask-claude.mjs "$PROMPT" --timeout-ms 120000 > "$TMPDIR/claude.txt" 2>"$TMPDIR/claude.err" &
[ "$HAS_CURSOR" = "1" ] && node .claude/skills/omega-cursor-cli/scripts/ask-cursor.mjs "$PROMPT" --yolo --trust --timeout-ms 120000 > "$TMPDIR/cursor.txt" 2>"$TMPDIR/cursor.err" &
wait
Stage 2: Anonymized Peer Review
- Collect all successful Stage 1 responses
- Assign anonymous labels: Response A, Response B, Response C, ...
- Maintain label_to_model mapping (e.g., A=gemini, B=codex, C=claude)
- Send all anonymized responses back to each available model with:
You are reviewing responses to this question: "$PROMPT"
Response A:
[content]
Response B:
[content]
Response C:
[content]
Evaluate each response for accuracy, completeness, and reasoning quality.
Then provide your FINAL RANKING (best to worst):
1. Response [X]
2. Response [Y]
3. Response [Z]
- Parse FINAL RANKING from each reviewer's output using regex:
\d+\.\s*Response [A-Z]
- Compute aggregate ranking (average position across all reviewers)
Stage 3: Chairman Synthesis
Send to chairman model (default: current Claude session or ask-claude.mjs):
You are the Chairman synthesizing a multi-model council discussion.
Original question: "$PROMPT"
Stage 1 Responses (with de-anonymized model names):
[Model]: [Response]
...
Stage 2 Peer Review Rankings:
Aggregate ranking: [best to worst with scores]
Synthesize the best insights from all responses into a single comprehensive answer.
Highlight areas of consensus and dissent. Provide the strongest possible answer.
Usage
Full council (all available models)
Skill({ skill: 'llm-council' })
Quick consultation (skip peer review)
When to Use
- High-stakes architectural decisions requiring multiple perspectives
- Code review where diverse model viewpoints reduce blind spots
- Plan critique and validation
- Resolving disagreements about implementation approach
- Cross-validation of security analysis
- When the user explicitly requests "council", "multiple perspectives", or "cross-validate"
Iron Laws
- ALWAYS check CLI availability before dispatch -- never assume a model is present
- ALWAYS anonymize responses before peer review -- model identity bias is real
- NEVER skip Stage 2 for high-stakes decisions -- the peer review is the core innovation
- ALWAYS preserve all 3 stages in output for transparency
- ALWAYS set per-model timeout to prevent one slow model from blocking the council
Anti-Patterns
| Anti-Pattern | Why Bad | Correct Approach |
|---|
| Dispatching to unavailable CLIs | Silent failure, missing responses | Run verify-setup.mjs first |
| Showing model names during peer review | Introduces identity bias | Use anonymous labels (Response A, B, C) |
| Using only 2 models for council | Peer review meaningless with 2 | Require minimum 3 for ranking value |
| Ignoring failed model responses | May miss degradation | Log failures, include in metadata |
| Running council for simple questions | Massive overhead for trivial queries | Reserve for high-stakes decisions |
Exit Codes
| Code | Meaning |
|---|
| 0 | Council completed successfully (at least 2 models responded) |
| 1 | Council failed (fewer than 2 models available or all timed out) |
Configuration
| Env Var | Default | Purpose |
|---|
LLM_COUNCIL_TIMEOUT_MS | 120000 | Per-model timeout for Stage 1 and Stage 2 |
LLM_COUNCIL_MIN_MODELS | 2 | Minimum models required for council to proceed |
LLM_COUNCIL_CHAIRMAN | (current session) | Chairman model for Stage 3 synthesis |
Integration Notes
- This skill does NOT require the llm-council-master FastAPI server
- Uses omega wrapper scripts directly via Bash backgrounding for parallelism
- Anonymized peer review is preserved from llm-council-master's design (its core innovation)
- Chairman synthesis can use the current Claude session (no additional CLI call needed)
- Temporary files stored in system temp dir, cleaned up after council completes
- Minimum 2 available models required for council to proceed
Collaboration Templates
Templates constrain each model's focus during council sessions, producing higher-quality synthesis than sending the same generic prompt to all models. Without a --template flag, the council operates in its default mode (all models receive the same prompt).
Available Templates
Review Template
| Field | Value |
|---|
| Agents | 2-3 (minimum 2) |
| Focus | Each agent reviews from their model's strengths (correctness, security, performance) |
| Synthesis | Chairman merges non-overlapping findings, deduplicates shared findings |
Roles:
roles:
- name: correctness-reviewer
focus: 'Review for logic errors, edge cases, off-by-one bugs, and correctness'
- name: performance-reviewer
focus: 'Review for performance bottlenecks, algorithmic complexity, and scalability'
- name: security-reviewer
focus: 'Review for security vulnerabilities, injection vectors, and data exposure'
synthesis_strategy: 'merge-by-category'
When to use: Code reviews, PR reviews, audit passes where multiple review dimensions matter.
Implementation Template
| Field | Value |
|---|
| Agents | 2-4 (minimum 2) |
| Focus | Plan, execute, verify staged workflow with sequential handoff |
| Synthesis | Sequential -- architect output feeds implementer, verifier checks result |
Roles:
roles:
- name: architect
focus: 'Design the approach, define interfaces, data flow, and module boundaries'
- name: implementer
focus: "Write the implementation following the architect's design exactly"
- name: verifier
focus: 'Verify the implementation matches the design and passes acceptance criteria'
synthesis_strategy: 'sequential'
When to use: Feature implementation where design and coding benefit from separation of concerns.
Research Template
| Field | Value |
|---|
| Agents | 2-3 (minimum 2) |
| Focus | Independent investigation of the same topic, then cross-compare findings |
| Synthesis | Side-by-side comparison matrix highlighting contradictions and agreements |
Roles:
roles:
- name: researcher-a
focus: 'Research the topic independently, cite sources, provide evidence-backed findings'
- name: researcher-b
focus: 'Research the same topic independently from a different angle, cite sources'
synthesis_strategy: 'compare-and-converge'
When to use: Technology evaluation, best-practice research, exploring solution spaces.
Debug Template
| Field | Value |
|---|
| Agents | 2-3 (minimum 2) |
| Focus | Each agent independently diagnoses the same bug and proposes a fix |
| Synthesis | Convergence analysis -- if 2+ agents agree on root cause, high confidence |
Roles:
roles:
- name: diagnostician-a
focus: 'Independently reproduce and diagnose the bug, propose root cause and fix'
- name: diagnostician-b
focus: 'Independently reproduce and diagnose the bug, propose root cause and fix'
synthesis_strategy: 'convergence'
When to use: Hard-to-diagnose bugs where independent analysis reduces bias.
Template Invocation
Skill({ skill: 'llm-council', args: '--template review' })
Skill({ skill: 'llm-council', args: '--template implementation' })
Skill({ skill: 'llm-council', args: '--template research' })
Skill({ skill: 'llm-council', args: '--template debug' })
Template Dispatch Behavior
When a --template is specified:
- Stage 1: Each model receives the base prompt PLUS its role-specific focus instruction from the template
- Stage 2: Peer review proceeds as normal (anonymized, ranked)
- Stage 3: Chairman uses the template's
synthesis_strategy to guide synthesis:
merge-by-category: Merge findings by review category, deduplicatesequential: Present outputs in role order, highlight handoff pointscompare-and-converge: Build side-by-side comparison matrixconvergence: Report agreement/disagreement on root cause, confidence score
Council Watchdog
Per-model idle monitoring with two-tier thresholds to detect hung or stalled models during council sessions.
Two-Tier Monitoring
| Tier | Threshold | Action |
|---|
| Idle Warning | 90 seconds of no output | Log warning, optionally send nudge prompt |
| Stall Timeout | 180 seconds of no output | Terminate model process, exclude from results |
Configuration
watchdog:
idle_warning_seconds: 90
stall_timeout_seconds: 180
nudge_prompt: 'Please continue with your analysis.'
action_on_stall: 'exclude'
| Env Var | Default | Purpose |
|---|
LLM_COUNCIL_IDLE_WARNING_S | 90 | Seconds before idle warning |
LLM_COUNCIL_STALL_TIMEOUT_S | 180 | Seconds before stall auto-exclude |
Integration with Stage 1
During parallel dispatch, each backgrounded model process is monitored independently:
- Start a per-model timer when the process launches
- If no output file growth after
idle_warning_seconds, log a warning
- If no output file growth after
stall_timeout_seconds, kill the process and set stall_timeout: true in council metadata
- Continue council with remaining models (graceful degradation)
Watchdog Output Metadata
{
"watchdog": {
"gemini": { "status": "completed", "duration_s": 45 },
"codex": { "status": "stall_timeout", "duration_s": 180, "excluded": true },
"claude": { "status": "completed", "duration_s": 62 }
}
}
Backward Compatibility
The watchdog is additive to the existing --timeout-ms global timeout. --timeout-ms remains the hard ceiling for the entire council session. The watchdog provides per-model granularity within that ceiling.
Inter-Agent Message Bus
Optional JSONL message file protocol that enables council members to share partial outputs during deliberation.
Overview
By default, council models work in complete isolation during Stage 1. The message bus enables optional partial-output sharing, useful for long deliberations where early findings from one model can inform others.
Opt-In
Enable with --enable-messaging flag. Without this flag, no message directory is created and the council operates in default isolated mode.
Message Protocol
Location: .claude/context/tmp/council-<session-id>/messages.jsonl
Message Schema:
{
"id": "msg-001",
"session_id": "council-2026-03-21-abc123",
"from": "gemini",
"to": "team",
"type": "partial_output",
"content": "Partial finding: JWT implementation has XSS risk in refresh flow",
"timestamp": "2026-03-21T10:30:00Z"
}
Message Types:
| Type | Purpose | When Sent |
|---|
partial_output | Share an intermediate finding or observation | During Stage 1, when a model has a partial result |
question | Ask the team a clarifying question | During Stage 1, when a model needs input |
agreement | Signal agreement with another model's finding | During Stage 2, after reading peer outputs |
disagreement | Signal disagreement with reasoning | During Stage 2, after reading peer outputs |
Read/Write Protocol
- Write: Each model appends messages to
messages.jsonl during Stage 1 execution
- Read (optional): Models can read
messages.jsonl between Stage 1 and Stage 2 for informed review
- Chairman read: Chairman reads all messages during Stage 3 synthesis for additional context
Cleanup
The session directory (.claude/context/tmp/council-<session-id>/) is deleted after the council completes, including the messages file.
Worktree Isolation
Optional per-agent git worktree isolation for council sessions where agents modify code.
When to Use
Worktree isolation is relevant only for templates that modify code:
| Template | Worktree Applicable? | Reason |
|---|
| Review | No | Read-only analysis |
| Implementation | Yes | Agents write code that may conflict |
| Research | No | Read-only research |
| Debug | Yes | Agents may apply experimental fixes |
Opt-In
Enable with --use-worktrees flag. Only takes effect when combined with --template implementation or --template debug.
Worktree Lifecycle
-
Create: For each participating agent, create a worktree:
git worktree add .claude/context/tmp/council-<session-id>/<agent-name> -b council/<session-id>/<agent-name>
-
Execute: Each agent operates within its isolated worktree directory. File modifications do not conflict across agents.
-
Merge: After council completes, the chairman reviews diffs from each worktree branch and merges non-conflicting changes back to the source branch.
-
Cleanup: Remove worktrees and branches:
git worktree remove .claude/context/tmp/council-<session-id>/<agent-name>
git branch -D council/<session-id>/<agent-name>
Conflict Resolution
When worktrees have overlapping changes to the same files:
- Chairman identifies conflicting hunks from each agent's diff
- Chairman selects the best version based on Stage 2 peer review rankings
- If ranking is inconclusive, chairman presents both versions with rationale for human decision
Platform Note
Worktree isolation follows existing agent-studio worktree safety rules. On Windows, ensure paths stay under the OS path length limit. Reference .claude/rules/ for worktree safety patterns.
Multi-Turn Council Sessions
Persistent session state that allows council deliberations to span multiple turns with user feedback between rounds.
Overview
By default, each council invocation is one-shot. Multi-turn sessions enable iterative refinement: the user reviews the synthesis, provides feedback, and the council continues deliberation with the additional context.
Opt-In
--multi-turn: Create a resumable session (generates a session ID)--resume SESSION_ID: Continue a previous session with new user input
Session State
Location: .claude/context/tmp/council-<session-id>/session.json
Schema:
{
"session_id": "council-2026-03-21-abc123",
"status": "active",
"turn_count": 2,
"max_turns": 5,
"original_prompt": "Review this auth implementation",
"template": "review",
"models": ["gemini", "codex", "claude"],
"turns": [
{
"turn": 1,
"stage_1_responses": { "gemini": "...", "codex": "...", "claude": "..." },
Continuation Protocol
When --resume SESSION_ID is used:
-
Load session.json from the session directory
-
Verify session is not expired (24-hour TTL from last_active)
-
Include previous turns' synthesis and user feedback in the next Stage 1 prompt:
Previous council synthesis: [Stage 3 output from last turn]
User feedback: [feedback text]
Continue the analysis with this additional context.
-
Models receive full conversation history for context continuity
-
Increment turn_count and update last_active
Configuration
| Env Var | Default | Purpose |
|---|
LLM_COUNCIL_MAX_TURNS | 5 | Maximum turns per session before forced closure |
Session Expiry
Sessions older than 24 hours are considered expired. Attempting to --resume an expired session returns an error with the session's last synthesis as context.
Cleanup
Session directories are cleaned up when:
- The session reaches
max_turns
- The user does not resume within 24 hours
- The user explicitly closes the session (no
--resume after final turn)
