Agent Council

Agent Council is a Python and Claude Code skill for examining a difficult question through several deliberately different perspectives. It builds a small council, runs the specialists concurrently, asks each specialist to review the other proposals, and produces a final synthesis.

This repository is a public prototype. It is useful for questions where disagreement and tradeoffs matter, but it does not make the output correct by consensus and it should not replace domain review for high-stakes decisions.

What It Does

One session follows five stages:

1. A council builder selects three to five complementary perspectives.
2. The specialists answer the same question in parallel.
3. Each specialist reviews the other proposals, excluding its own.
4. A synthesis agent combines the strongest supported points.
5. Markdown and JSON results are saved locally under sessions/.

The runtime is a CLI. It does not require a web server or database.

Requirements

• Python 3.11 or newer; CI covers Python 3.11 and 3.13.
• An OpenAI API key.
• API access to the selected GPT-5.6 preview model.

GPT-5.6 is currently available only to approved preview participants. A valid API key does not guarantee that its project can use these models. See the GPT-5.6 preview announcement and current model guidance.

Installation

Clone the repository and create an isolated environment:

git clone https://github.com/ntguion/perspective-gen-skill.git
cd perspective-gen-skill
python3.11 -m venv .venv
source .venv/bin/activate
python scripts/install.py

On Windows PowerShell, activate the environment with:

.venv\Scripts\Activate.ps1
python scripts/install.py

The installer:

• installs the reviewed ranges in requirements.txt;
• validates the API key with an API request;
• stores it at ~/.config/agent-council/credentials.yaml;
• creates config/limits.yaml with the selected local spend limits.

On Unix, the installer creates the credential directory and file with user-only permissions. This reduces accidental exposure; it is not isolation from other processes running with the same user privileges.

Running a Session

The runner performs its own buffered spend check before loading credentials or starting a paid session:

python scripts/run_session.py \
  --question "Should this service use a modular monolith or microservices?"

For a sensitive or long question, keep the text out of shell history:

python scripts/run_session.py --question-file ./question.txt

You can preview the estimate without running a session:

python scripts/check_spend.py \
  --estimate "Should this service use a modular monolith or microservices?"

Supporting Context

Context is limited to UTF-8 .txt, .md, .json, .yaml, .yml, and .csv files:

python scripts/run_session.py \
  --question-file ./question.txt \
  --files ./requirements.md ./constraints.yaml

The loader accepts at most ten files, keeps at most 5,000 characters from each file, and caps the combined context at 20,000 characters. Filenames—not absolute paths—are written to the transcript. Binary documents such as PDF and PowerPoint files are not supported.

GPT-5.6 Models and Pricing

The explicit default is gpt-5.6-sol. The CLI also supports the lower-cost Terra and Luna variants:

Model	Role	Input / 1M tokens	Output / 1M tokens
gpt-5.6-sol	Flagship quality; default	$5.00	$30.00
gpt-5.6-terra	Balanced quality and cost	$2.50	$15.00
gpt-5.6-luna	Efficient, high-volume work	$1.00	$6.00

These standard text-token rates were verified on 2026-07-10 against OpenAI's GPT-5.6 preview announcement. Pricing and availability can change.

Choose another family member with --model:

python scripts/run_session.py \
  --question-file ./question.txt \
  --model gpt-5.6-terra

The local estimate uses reported input and output tokens at the table's standard rates. It does not calculate web-search fees, priority processing, cache-write premiums, cached-input discounts, or any other billing modifier. Check the API dashboard for authoritative usage and cost.

Spend Controls

The default example limits are $2 per session and $50 total. Edit the ignored, user-specific config/limits.yaml to change them.

Before a session, the runner estimates a five-member council, repeats the bounded context cost across the builder and specialists, and adds a 50% buffer. It blocks the run if that estimate exceeds either configured limit. This is a preflight guard, not a billing guarantee or a mechanism that can stop an API request already in progress.

After a successful session, the runner records the locally estimated token cost and increments the session count. The API dashboard remains the source of truth.

Output

Each completed run creates:

sessions/YYYYMMDD_HHMMSS_microseconds/
├── results.md
└── full_transcript.json

Both files can contain the original question, specialist responses, reviews, and synthesis. The directory is ignored by Git, but the files should still be treated according to the sensitivity of the source material.

Data and Credential Boundaries

• Questions and loaded context are sent to the OpenAI API.
• Specialists with web search enabled may send derived queries to that hosted tool.
• The skill stores its API key outside the repository and never includes it in session output.
• Processes running as the same operating-system user may still be able to read the credential file.
• Local transcripts may contain confidential or personal content even when source paths are sanitized.
• Do not commit config/limits.yaml, credentials, or sessions/ output.

Validation

Install the development requirements and run the offline checks:

python -m pip install -r requirements-dev.txt
ruff check .
pytest

The tests cover GPT-5.6 pricing, spend-limit enforcement, credential-file creation, context bounds, self-review exclusion, output-path sanitization, and model construction without making a live API call.

Limitations

• GPT-5.6 model access is limited preview and cannot be verified without an entitled API project.
• No live API call runs in CI, so provider behavior, model availability, latency, and response quality are not continuously verified.
• Multiple model perspectives can repeat the same misconception or converge on a weak premise.
• Peer review and synthesis improve comparison structure; they do not prove factual accuracy.
• Text context is truncated and binary document parsing is intentionally unsupported.
• Web search can add latency, tool charges, and external data dependencies.
• Cost estimates are local approximations and exclude several API billing modifiers.
• The current YAML spend ledger is designed for one local session at a time, not concurrent writers.

Repository Layout

.
├── SKILL.md
├── core/
│   ├── agent_builder.py
│   ├── config.py
│   ├── context.py
│   ├── cost_tracking.py
│   ├── council.py
│   └── credentials.py
├── scripts/
│   ├── check_spend.py
│   ├── install.py
│   └── run_session.py
├── config/limits.yaml.example
├── references/
├── requirements.txt
├── requirements-dev.txt
└── tests/

License

MIT. See LICENSE.