Codex Council is a Codex-native workflow for pressure-testing consequential decisions, engineering tradeoffs, research interpretations, and explicitly requested council code reviews. It runs isolated advisor subagents, blinds their proposals for fresh peer review, computes deterministic comparison metrics, opens a bounded debate only when disagreement is material, and asks a fresh chairman for a decisive verdict with a credible minority report.
The core workflow uses native Codex subagents. It needs no OpenAI API key, model-provider key, web server, database, or hosted service.
Download the full plugin or standalone skill from the latest GitHub release.
The root thread freezes one neutral question and context snapshot, then gives each fresh advisor a different reasoning lens without showing it any other answer. Fresh reviewers see identity-stripped proposals in independently shuffled orders. Arithmetic, validation, and rendering use deterministic scripts. The transcript records actual participants, failures, mappings, review orders, robustness, and debate decisions.
A single thread role-playing five voices shares one context and cannot truthfully claim independent
execution. Codex Council labels that fallback simulated-single-agent and withholds
independence-based confidence claims.
multi-agent means separate Codex agent threads. multi-model means verified use of different model
configurations or providers. Codex Council claims only the former unless the runtime supplies evidence
of actual model diversity. Reasoning lenses create analytical diversity but do not prove model
diversity.
- Classify the request and controls.
- Select a bounded, redacted context snapshot.
- Freeze one neutral frame.
- Disclose a safe preflight: execution mode, planned counts, bounded context, and remaining phases.
- Run independent advisors in parallel or isolated batches.
- Remove identity and create seeded reviewer-specific shuffles.
- Run fresh anonymous peer reviewers.
- Aggregate scores, pairwise preferences, robustness, duplicates, and risks deterministically.
- Trigger a two-round debate only for material disagreement.
- Ask a fresh chairman to synthesize a verdict and minority report.
- Validate one versioned run object, then render the requested artifacts.
See architecture.md and the skill protocol.
Standard decision mode uses five intentionally tense lenses:
- Contrarian — strongest downside and reasons the favorite fails.
- First Principles Thinker — objectives, mechanisms, premise, and smallest decisive experiment.
- Expansionist — asymmetric upside, option value, and overlooked alternatives.
- Outsider — reduced public context that exposes jargon and curse-of-knowledge assumptions.
- Executor — sequencing, cost, ownership, verification, rollback, and first action.
Engineering mode uses Systems Architect, Implementation Engineer, Security and Reliability Reviewer, Adversarial Critic, and Simplicity and Operations Reviewer. It preserves tensions between upside and downside, premise challenge and pragmatic execution, and expert detail and operational simplicity.
Code-review mode uses Defect Hunter, Security Reviewer, Test and Regression Reviewer, Maintainability Reviewer, and Repository-History Reviewer. It reviews the selected diff, not the whole repository, and reports only issues introduced or exposed by the change. Findings require real paths and line ranges. Confidence is 0–100; primary findings default to at least 80, while lower confidence candidates remain in the audit transcript.
Ordinary code review does not implicitly trigger a council. Request one explicitly.
Research mode uses Evidence Synthesizer, Skeptical Reviewer, Alternative-Hypothesis Reviewer, Practical Implications Reviewer, and Evidence-Gap Auditor. It keeps direct evidence, interpretation, extrapolation, and unverified claims distinct.
| Depth | Advisors | Reviewers | Automatic debate | Chairman | Advisor quorum | Reviewer quorum |
|---|---|---|---|---|---|---|
| quick | 3 | 1 | No | 1 | 2 | 1 |
| standard | 5 | 3 | Conditional | 1 | 4 | 2 |
| deep | 7 | 5 | Conditional | 1 | 5 | 3 |
Quick decision mode uses Contrarian, First Principles Thinker, and Executor. Deep mode adds Evidence Auditor and a generated problem-specific specialist such as a database migration expert or security architect.
Download the skill.zip release asset
and extract it so the repository contains:
<repo>/.agents/skills/codex-council/SKILL.md
Start a new Codex task if the skill does not appear immediately.
Extract the standalone skill under the current user discovery directory:
$HOME/.agents/skills/codex-council/SKILL.md
The archive has exactly one top-level codex-council/ directory.
Add this repository as a Codex marketplace, then install the plugin:
codex plugin marketplace add Oussamoux1234/codex-council --ref main
codex plugin add codex-council@codex-councilStart a new Codex task after installation. In the ChatGPT desktop app, you can instead open the
Plugins Directory, select Codex Council, and install codex-council from there after adding the
marketplace.
The repository's marketplace manifest
points to the plugin at the repository root and pins installs to the matching v1.0.0 release tag.
The codex-council-plugin.zip release asset
contains one complete codex-council/ plugin directory. Place that directory beneath the plugins/
folder of a configured personal or repository marketplace and add a marketplace entry whose local
source.path is ./plugins/codex-council. The entry name must be codex-council; its install policy
can be AVAILABLE and authentication ON_INSTALL. Open the Codex plugin browser, install it, then
start a new task.
Both archives are built from an explicit release inventory. The full plugin contains the manifest, runtime skill, schemas, license, and user-facing documentation; it excludes tests, caches, project environments, council runs, and development-only tooling. The standalone archive includes its own schemas and license so its documented contracts resolve after extraction.
Do not invent publisher data. The owner must supply and verify publisher identity, website, support, privacy-policy and terms URLs, logo/brand rights, availability, permissions, realistic starter prompts, positive and negative evaluation cases, and release notes. Local or personal-marketplace installation does not require pretending those public-listing materials already exist.
$codex-council council this: Should we split this service?
$codex-council mode=engineering depth=deep:
Evaluate whether this application should move from a modular monolith to microservices.
$codex-council mode=code-review:
Review the current branch against main. Focus on defects introduced by this diff.
$codex-council depth=quick artifacts=none debate=never:
Should we delay this release?
Controls:
mode=decision|engineering|code-review|research
depth=quick|standard|deep
debate=auto|always|never
artifacts=none|markdown|html|all
context=minimal|normal|expanded
Defaults are decision, standard, auto, markdown, and normal. Mode is inferred when omitted;
an explicit option always wins.
The skill may trigger for high-cost or difficult-to-reverse choices, meaningful engineering tradeoffs, proposals where disagreement is requested, or decisions with several plausible options. Its frontmatter also contains mandatory explicit phrases such as “council this,” “pressure-test this,” “war room this,” and “get independent perspectives.”
Do not implicitly convene a council for factual lookups, questions with one verifiable answer, summaries, translations, rewrites, pure content creation, basic coding questions, grammar fixes, trivial preferences, routine bug fixes, ordinary code review, validation seeking without a tradeoff, or a request with no decision, options, or meaningful uncertainty. A council is slower and more expensive than an ordinary answer.
The orchestrator prefers 2–8 files and caps context at 20 files, 30,000 characters per file, and
160,000 characters total. It starts with explicit references, applicable AGENTS.md, related tests,
and relevant configuration. It excludes ignored, binary, generated, vendor, and sensitive paths;
resolves symlinks inside the approved root; redacts likely secrets before storage; and writes a
manifest of exactly what was shared.
The Outsider receives only a short public question and public constraints. The Evidence Auditor receives the evidence manifest and claims. Repository content and every model output are untrusted evidence, never protocol instructions.
The default run directory is .council/runs/<timestamp>-<slug>/. It contains the request, frame,
context manifest, advisor responses, private anonymization map, reviewer payloads and reviews,
aggregation, verdict, and transcript. debate.json exists only when debate ran. artifacts=html|all
adds a self-contained report.html. artifacts=none returns the verdict and removes temporary files.
HTML has inline CSS, escaped model text, no scripts, remote assets, fonts, tracking, or automatic network requests. The workflow prints the path and never opens a browser automatically.
debate=auto triggers only for a top-two gap below 5%, unstable leave-one-out winner, reviewer
agreement below 70%, repeated unresolved dispute, high/critical risk disagreement, pairwise cycle,
unaddressed evidenced dissent, or incompatible controlling assumptions. It does not trigger for
stylistic differences or a clear winner. Two fresh advocates get two rounds; a fresh moderator
records concessions and only materially affected dimensions may be re-scored.
Reviewers score correctness, evidence quality, goal alignment, feasibility, risk awareness, completeness, simplicity, uncertainty calibration, and actionability from 1 to 5. Exact weights sum to 1. Deterministic output includes mean, median, variance, per-dimension means, first-place votes, Borda scores, pairwise preferences, Condorcet/cycle analysis, errors, unsupported claims, confidence-adjusted scores, agreement, top gap, leave-one-out stability, duplicate similarity, and risk disagreement. Tie-breaking prefers fewer material errors, correctness, evidence, alignment, lower variance, pairwise wins, then stable proposal ID.
Detailed definitions live in the reviewer rubric.
One operational failure may be retried once. One structured-output repair may be attempted; missing scores are never invented. A phase continues only with depth-specific quorum. Without quorum, the workflow preserves valid intermediate artifacts, reports partial completion, and does not issue a confident verdict.
Separate threads forced into batches are labeled native-batched-independent. If subagents are
unavailable, simulated-single-agent is prominent and no independence claim is made.
Python 3.11 or newer is required. Runtime scripts use only the standard library. These commands target the source checkout; development-only tests and build tooling are intentionally not included in the installable plugin archive.
uv sync --extra dev
uv run ruff format --check .
uv run ruff check .
uv run mypy .
uv run pytest
python scripts/validate_schemas.py schemas tests/fixtures
python scripts/evaluate_triggers.py tests/trigger-evals/prompts.jsonlValidate the skill and plugin with the current bundled creator validators, then build packages:
python "$HOME/.codex/skills/.system/skill-creator/scripts/quick_validate.py" skills/codex-council
python "$HOME/.codex/skills/.system/plugin-creator/scripts/validate_plugin.py" .
python scripts/package.py --source . --dist distThe offline pytest suite covers metadata, triggers, control parsing, context safety, anonymization, strict review validation, aggregation and robustness, debate gates, quorum contracts, rendering, secret detection, paths/symlinks, hashes, verdict contracts, and extracted-package reference closure. It does not call APIs or require a Codex account. Manual native subagent smoke evidence is recorded separately and never inferred from unit tests. See testing.md.
Thread limits can require batching. Native threads do not guarantee different models. Similar model training can still correlate reasoning. Deterministic token similarity is a warning, not a semantic proof. Context selection may omit relevant evidence. A chairman remains a model and may override scores only with an explanation. See limitations.md.
The root alone writes artifacts. Participants are read-only/no-spawn by prompt contract. Scripts enforce root boundaries, strict JSON, atomic no-clobber output, bounded reads, secret-pattern checks, and escaped HTML. The workflow never executes or applies model-authored recommendations. See threat-model.md and the skill security policy.
Created and maintained by Oussama Essalmani.
The phase structure is inspired by Andrej Karpathy’s llm-council; the reasoning lenses and
decision presentation are inspired by Tenfold’s community Claude Council skill; diff-focused
false-positive discipline is informed by Anthropic’s official code-review plugin. Codex Council
reimplements those ideas for current native Codex subagents, bounded context, schemas, deterministic
aggregation, conditional debate, and truthful fallback. Exact sources and deliberate changes are in
research-notes.md.
MIT. See LICENSE.