
llm-council
Multi-LLM Council for adversarial debate, cross-validation, and structured decision-making
- GitHub stars
- 97
Install
/plugin install llm-council@the-llm-councilRun it inside Claude Code after adding the marketplace with /plugin marketplace add sherifkozman/the-llm-council.
Contents
Discovered from sourceSkills 1
LLM Council Skill (v0.9.0)
Multi-model council: parallel drafts, adversarial critique, validated synthesis.
This skill requires the
the-llm-councilpackage to be installed. The skill provides the agent-side interface; actual runs happen through the installedcouncilCLI.
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:
| Provider | Environment Variable |
|---|---|
| OpenRouter | OPENROUTER_API_KEY |
| OpenAI | OPENAI_API_KEY |
| Anthropic | ANTHROPIC_API_KEY |
| Gemini API | GOOGLE_API_KEY or GEMINI_API_KEY |
| Vertex AI | GOOGLE_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:
| Subagent | Modes | Use for |
|---|---|---|
drafter | impl, arch, test | implementation, architecture, tests |
critic | review, security | code review and security analysis |
planner | plan, assess | execution 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
| Option | Purpose |
|---|---|
--mode <mode> | Select a runtime mode for drafter, critic, or planner |
--json | Return structured JSON |
--verbose | Show resolved execution details and council phases |
--providers | Explicit provider list. Omit to use config defaults |
--models | Explicit model list |
--runtime-profile bounded | Lower latency and token budgets |
--timeout | Per-attempt seconds, 10-3600 (default 120); use the default runtime profile for long deadlines |
--reasoning-profile off|light | Request reduced reasoning; inspect provider compilation metadata for unsupported or uncontrolled native effort |
--route | Follow a router decision into the chosen subagent/mode |
--files | Add file context, capped at 50,000 characters/file and 200,000 retained characters total |
--dry-run | Show the resolved plan without executing |
--schema | Use 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:
openrouteropenaianthropicgeminigemini-clivertex-aiclaudecodex
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, testscritic --mode review|security- Review and security analysisplanner --mode plan|assess- Plans and assessmentsresearcher- Technical researchsynthesizer- Merge findingsrouter- 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