Multi-LLM Council for adversarial debate, cross-validation, and structured decision-making

GitHub stars
97

Install

/plugin install llm-council@the-llm-council

Run it inside Claude Code after adding the marketplace with /plugin marketplace add sherifkozman/the-llm-council.

Contents

Discovered from source

Skills 1

LLM Council Skill (v0.9.0)

Multi-model council: parallel drafts, adversarial critique, validated synthesis.

This skill requires the the-llm-council package to be installed. The skill provides the agent-side interface; actual runs happen through the installed council CLI.

Agent Invocation Contract

For tool-driven runs, read the portable invocation contract before execution. It requires Council 0.8.5 or later and applies to Codex, Claude Code, Hermes and generic subprocess callers. Use an explicit executable/CWD, task-file or stdin input, ordered providers/models, a unique result file, and wait for completion. Inspect execution_status and full diagnostics; exit 0 or success: true alone is not a complete review. Never retry a still-running run. Inspect delivered source/draft coverage, including profile-0 compaction. Only submitted evidence cuts count toward compaction-based degradation; synthesis_attempts counts adapter starts, not queued requests. Inspect cancellation evidence, artifact occurrences and persistence diagnostics. Ingestion counts do not prove delivery; Council pipeline cuts are not source defects. A hard-killed run can leave a running ledger row without a live process; do not automatically repair the row or restart the run. The contract explains CLI/library runtime identity and the started/settled execution manifests. The settled snapshot precedes ledger finalization, so read the terminal ledger separately; snapshots are not a heartbeat or repair service.

The built-in reviewer keeps prepared-coverage metadata separate from source evidence in critique/synthesis prompts; this added boundary does not apply to security/custom schemas. Schema-validation exhaustion fails with drafts, critique and errors preserved, rather than manufacturing findings from prose. Invalid raw synthesis is artifact-only if storage succeeds. Exception-triggered fallback to a schema-valid JSON draft remains degraded; valid JSON does not prove semantic truth.

Setup

Install the package:

pip install 'the-llm-council>=0.8.5'

Optional extras:

pip install 'the-llm-council[anthropic,openai,gemini]>=0.8.5'
pip install 'the-llm-council[vertex]>=0.8.5'

These commands require a published release. For an existing pinned uv tool, follow the portable contract's exact-version reinstall procedure; an isolated test install does not update the executable used by real callers.

Configure at least one provider key:

ProviderEnvironment Variable
OpenRouterOPENROUTER_API_KEY
OpenAIOPENAI_API_KEY
AnthropicANTHROPIC_API_KEY
Gemini APIGOOGLE_API_KEY or GEMINI_API_KEY
Vertex AIGOOGLE_CLOUD_PROJECT or ANTHROPIC_VERTEX_PROJECT_ID + ADC

Verify what is usable in the current shell:

council doctor
council doctor --deep --provider claude --provider gemini-cli --provider codex

Canonical Surface

council run <subagent> [--mode <mode>] "<task>" [options]

Primary subagents:

SubagentModesUse for
drafterimpl, arch, testimplementation, architecture, tests
criticreview, securitycode review and security analysis
plannerplan, assessexecution plans and decision assessments
researcher—research with sources and evidence
router—task classification and routed handoff
synthesizer—final merged output

Legacy aliases such as implementer, architect, reviewer, red-team, assessor, test-designer, and shipper still work, but they are no longer the preferred interface.

Common Commands

# Implementation
council run drafter --mode impl "Add pagination to users API"

# Architecture
council run drafter --mode arch "Design a caching layer"

# Tests
council run drafter --mode test "Design tests for cursor pagination"

# Review
council run critic --mode review "Review auth changes"

# Security
council run critic --mode security "Analyze auth system vulnerabilities"

# Planning
council run planner --mode plan "Plan MongoDB to PostgreSQL migration"

# Assessment
council run planner --mode assess "Redis vs Memcached for sessions"

# Research
council run researcher "Research WebSocket libraries for Node.js"

# Router handoff
council run router "Should we buy or build auth?" --route

Useful Options

OptionPurpose
--mode <mode>Select a runtime mode for drafter, critic, or planner
--jsonReturn structured JSON
--verboseShow resolved execution details and council phases
--providersExplicit provider list. Omit to use config defaults
--modelsExplicit model list
--runtime-profile boundedLower latency and token budgets
--timeoutPer-attempt seconds, 10-3600 (default 120); use the default runtime profile for long deadlines
--reasoning-profile off|lightRequest reduced reasoning; inspect provider compilation metadata for unsupported or uncontrolled native effort
--routeFollow a router decision into the chosen subagent/mode
--filesAdd file context, capped at 50,000 characters/file and 200,000 retained characters total
--dry-runShow the resolved plan without executing
--schemaUse a custom output schema

These file limits count characters, not KB. Per-file overflow truncates input; total retained overflow fails before calls. Inspect execution_plan.context_preparation.files and degradation_report.context_warnings; never present truncated input as a full review. Context warnings remain visible with graceful degradation disabled. The caller's outer deadline must cover the whole workflow, not just one attempt. The bounded profile retains shorter phase caps regardless of a larger timeout. Successful deep doctor probes prove reachability, not large-review completion or quality. Codex base doctor checks default-context record admission and login status, not generation readiness.

Provider Names

Canonical provider names:

  • openrouter
  • openai
  • anthropic
  • gemini
  • gemini-cli
  • vertex-ai
  • claude
  • codex

User-selected providers and models should be respected. Health checks and deep doctor probes are for diagnostics, not for silently overriding explicit configuration.

--models accepts literal IDs in provider order, not provider:model mappings such as codex:gpt-5.4. Keep official slash namespaces and colon suffixes such as openai/gpt-5.4 and qwen/qwen3.6-plus:free intact. Runtime identity must distinguish the selected executable/version from the requested model; the latter is not a provider-confirmed model identity.

Claude Code admission is capability-based, not pinned to builds: each call checks the selected binary's help for required controls, including the chosen auth mode and optional effort. Report missing controls and the observed path/version; never drop isolation flags to continue. Base doctor proves advertised syntax only, not authentication, isolation semantics or generation. New builds are not rejected just because their version is unfamiliar. See the invocation contract. The Codex provider requires a current compatibility record for the selected build and request context. It verifies a private copy before execution; unknown or changed builds fail closed. Requests proceed only when the fetched record is current and matches the selected build and context; unavailable, expired or unrecorded combinations fail closed. The 0.8.9 record includes Codex 0.167.0 on six official npm platform builds; see the 0.8.9 qualification notes for evidence and limits. Do not bypass the check or treat synthetic tests as proof of live-provider readiness. Base doctor covers the default model, default reasoning, text output and login status only; it does not prove a credential works or every model is ready.

When To Use It

Use council for:

  • non-trivial implementation work
  • architecture and system design
  • code review and security analysis
  • planning and build-vs-buy style decisions
  • research that benefits from multiple models critiquing each other

Skip it for:

  • trivial one-line edits
  • simple lookups
  • tasks where a single direct model call is clearly enough

Commands 1

Run the LLM Council with the specified subagent and task.

Requires: Council 0.8.5 or later and usable credentials for each selected provider.

Subagents

  • drafter --mode impl|arch|test - Implementation, architecture, tests
  • critic --mode review|security - Review and security analysis
  • planner --mode plan|assess - Plans and assessments
  • researcher - Technical research
  • synthesizer - Merge findings
  • router - Task classification

Execution

Read the portable invocation contract from the installed plugin before calling Council. Resolve the intended executable, verify its version, preserve the user's providers/models, and pass the task through a UTF-8 input file or stdin. Use an explicit CWD and a unique JSON output file. Wait on the original process handle, then inspect the complete result and execution_status even on nonzero exit; success: true alone is insufficient. A request_changes verdict is not an execution failure; degraded coverage is not a full review. Never automatically retry a live or valid degraded run, invoke a personal wrapper, or bypass a client's credential/approval policy.

The built-in reviewer distinguishes prepared-coverage metadata from source evidence; the added prompt boundary leaves security/custom schemas unchanged. Exhausted schema validation fails with drafts, critique and errors preserved: arbitrary prose is not converted into reviewer findings. Invalid raw synthesis is artifact-only if storage succeeds. Exception-triggered schema-valid JSON draft fallback remains degraded and is not evidence of semantic truth or approval.

File limits count characters, not KB: 50,000 per file and 200,000 retained in total. Inspect execution_plan.context_preparation.files and degradation_report.context_warnings; truncated input is not a full-file review. --timeout accepts 10-3600 seconds per attempt (default 120), not per workflow. Use --runtime-profile default for long attempt deadlines and set the caller's outer deadline separately; bounded retains shorter phase caps. Doctor reachability is not proof that a large review completed.

Ingestion counts are not delivered coverage. Inspect execution_plan.context_preparation.coverage and execution_plan.phase_prompt_compaction, including profile 0; source selection and draft cuts are pipeline limitations, not source defects. Only submitted evidence cuts count toward compaction-based degradation. Read degradation_report.total_retries separately from planned_retries, the top-level synthesis_attempts, completed evidence on cancellation, execution_plan.artifact_occurrences and execution_plan.persistence. Synthesis attempts count adapter starts, not queued requests. The contract covers CLI/library runtime identity and started/settled execution manifests; the settled snapshot precedes ledger finalization, not a terminal-ledger guarantee. A hard-killed run's running ledger row does not prove liveness; never automatically repair it or restart a paid run.

Preserve official slash/colon model IDs, but reject provider:model mappings. Distinguish selected executable/version from requested, not confirmed, model identity. Follow the contract for an approved exact-version uv tool reinstall; an isolated environment does not update the real caller's executable or pin. Do not delete native installations or change PATH to hide selection mismatches.

Claude CLI admission checks required capabilities on every call, not exact build numbers. Report missing controls from doctor; never strip isolation flags to proceed. Help advertises syntax, not authentication or behavioral compatibility.

Codex uses a separately maintained compatibility record. It admits only exact executable/resource snapshots and request contexts in a current, unexpired record; unknown or changed builds and unrecorded model, authentication, reasoning or output combinations fail closed. Independently qualified builds can be added to the record without a Council package release. The 0.8.9 record includes Codex 0.167.0 across six official npm platform builds; see the 0.8.9 qualification notes. Qualification does not establish support for other builds or contexts. Report doctor diagnostics with the selected executable and observed version; do not infer behavioral support from version strings or advertised flags.

Sponsors

Details

Marketplace
sherifkozman/the-llm-council
Category
Community