The Council

A four-tier AI agent orchestration system built as a Claude Code MCP server.

The Council is a TypeScript Model Context Protocol (MCP) server with four Claude agents. When you give it a problem, it figures out the complexity and sends it to the right agents. A formatting task goes straight to the fast Aide (Haiku). A coding task goes to the Executor (Sonnet). A design or architecture problem first goes through the Chancellor (Opus) for a plan, then the Executor runs each step, delegating simple sub-tasks to the Aide. After each Executor or Aide output, the Supervisor (Haiku) acts as an active quality gate — rejecting outputs that miss the mark and triggering a retry with its feedback attached, up to a configurable limit.

Sub-agents run via the claude CLI — the same one Claude Code uses. If you already have Claude Code installed, no separate API key or extra cost is needed. The install script finds the claude binary and wires it up automatically. Alternatively, set ANTHROPIC_API_KEY in the MCP server env for CI or API-key-based setups.

---

How It Works

Complexity routing uses a fast keyword + word count check with no extra LLM call.

Signal	Complexity	Agents invoked
Word count > 60, or keywords: plan, design, architect, strategy, analyze, assess, risk	Complex	Chancellor -> Executor -> Aide -> Supervisor
Word count 15-60, no strong signal	Simple	Executor -> Aide (as needed) -> Supervisor
Word count < 15, keywords: format, convert, transform, clean, list, count	Trivial	Aide -> Supervisor

---

Agent Roles

Agent	Model	Role	Tools	Max turns
Chancellor	claude-opus-4-6	Deep analysis, planning, risk assessment	Read, Glob, Grep (read-only)	3
Executor	claude-sonnet-4-6	Implementation, code, delegation	Read, Write, Edit, Bash, Glob, Grep	10
Aide	claude-haiku-4-5	Formatting, data transformation, utilities	Read	3
Supervisor	claude-haiku-4-5	Output review, quality flags, intent alignment	None (pure reasoning)	2

By default the Supervisor is an active quality gate: when it rejects an output (approved: false), the orchestrator re-invokes the agent with the Supervisor's flags appended as feedback, up to COUNCIL_EVAL_RETRIES times (default 2 → 3 total attempts). If the output is still flagged after the retry budget is exhausted, the result is surfaced anyway with the flags visible — nothing is silently dropped. Set COUNCIL_EVAL_RETRIES=0 to revert to pure-advisory mode. If the Supervisor itself errors, orchestration continues without a verdict and a warning is logged.

---

Orchestration Flow

---

MCP Tools

Tool	Description	Key inputs
orchestrate	Route a problem through The Council. Complexity is assessed automatically.	problem (string, max 10 000 chars)
consult_chancellor	Invoke the Chancellor directly for deep strategic analysis and a structured plan.	problem, context?
execute_with_executor	Invoke the Executor directly for implementation. Has file and shell tool access.	task, plan_context?, session_id?
delegate_to_aide	Invoke the Aide directly for simple, well-defined tasks.	task (max 2 000 chars), task_id?, context?, session_id?
get_council_state	Retrieve session state by ID, or list all active sessions.	session_id?
get_supervisor_verdicts	Retrieve Supervisor verdicts for a session. Use flagged_only to surface only issues.	session_id, flagged_only?

---

Installation

Requirements: Node.js 22+

One-liner

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/iamvirul/the-council/main/install.sh | bash

Windows (PowerShell)

irm https://raw.githubusercontent.com/iamvirul/the-council/main/install.ps1 | iex

Both scripts detect your claude CLI location and configure both Claude Desktop and Claude Code CLI automatically. No API key or extra cost if you already have Claude Code. Nothing is installed globally.

Target	Config location
Claude Desktop (macOS)	~/Library/Application Support/Claude/claude_desktop_config.json
Claude Desktop (Linux)	~/.config/Claude/claude_desktop_config.json
Claude Desktop (Windows)	%APPDATA%\Claude\claude_desktop_config.json
Claude Code CLI	Registered via claude mcp add (project-scoped)

Restart Claude Code after running the script.

Manual setup

Add this to your Claude Code MCP config. Replace the PATH value with the directory containing your claude binary (run which claude to find it):

{
  "mcpServers": {
    "the-council": {
      "command": "npx",
      "args": ["-y", "council-mcp"],
      "env": {
        "PATH": "/path/to/claude/bin:/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}

If you prefer API key auth instead, use "ANTHROPIC_API_KEY": "sk-ant-..." in the env block.

Restart Claude Code and the tools will appear.

Persistent sessions (optional)

By default sessions are stored in memory and cleared when the MCP server restarts. To persist sessions across restarts, add COUNCIL_PERSIST to the env block:

Value	Storage	Notes
memory	In-process (default)	Cleared on restart, no setup needed
file	~/.council/sessions/<id>.json	Zero dependencies, human-readable
sqlite	~/.council/council.db	Recommended — fast, transactional, concurrent-safe

{
  "mcpServers": {
    "the-council": {
      "command": "npx",
      "args": ["-y", "council-mcp"],
      "env": {
        "PATH": "/path/to/claude/bin:/usr/local/bin:/usr/bin:/bin",
        "COUNCIL_PERSIST": "sqlite"
      }
    }
  }
}

Sessions older than 7 days are automatically expired on startup and periodically in file and SQLite modes.

Token compression (optional)

The Council can make multiple agent calls per orchestration. Enable Caveman compression to reduce output tokens from internal agents (Chancellor, Executor, Aide) by up to 50-60%, with no loss of technical accuracy. The Supervisor is exempt — its user-facing recommendation stays in normal prose.

Add COUNCIL_CAVEMAN to the env block:

Value	Style	Measured savings
off	Normal verbose output (default)	—
lite	Drop filler and pleasantries, keep grammar	~20%
full	Fragments, flat bullets, 50% word budget enforced	~50-60%
ultra	Telegraphic, abbreviations, symbols	~60-70%

{
  "mcpServers": {
    "the-council": {
      "command": "npx",
      "args": ["-y", "council-mcp"],
      "env": {
        "PATH": "/path/to/claude/bin:/usr/local/bin:/usr/bin:/bin",
        "COUNCIL_PERSIST": "sqlite",
        "COUNCIL_CAVEMAN": "full"
      }
    }
  }
}

full is the recommended setting — it hits the target savings without sacrificing readability of intermediate agent outputs. The active mode is recorded in each session's metrics.caveman_mode field, visible via get_council_state.

Supervisor evaluation loop (optional)

The Supervisor reviews every Executor and Aide output. When approved: false, the orchestrator re-invokes the agent with the Supervisor's flags and recommendation appended as feedback, giving the agent a chance to address the issues before the result surfaces. If the retry budget is exhausted, the flagged result surfaces anyway — no output is silently dropped.

Configure with COUNCIL_EVAL_RETRIES (number of additional attempts after the initial one):

Value	Behaviour	Worst-case agent calls per step
0	Supervisor is advisory only — matches pre-0.5 behaviour	1
2 (default)	Up to 2 retries per flagged step — recommended	3
5	Hard ceiling — clamped at 5	6

Values outside [0, 5] are clamped; non-integer values fall back to the default. Each retry spends tokens for both the re-invoked agent and the Supervisor re-review, so high values trade quality for cost. The retry count for a session is recorded in metrics.eval_retries, visible via get_council_state.

{
  "mcpServers": {
    "the-council": {
      "command": "npx",
      "args": ["-y", "council-mcp"],
      "env": {
        "PATH": "/path/to/claude/bin:/usr/local/bin:/usr/bin:/bin",
        "COUNCIL_PERSIST": "sqlite",
        "COUNCIL_EVAL_RETRIES": "2"
      }
    }
  }
}

Registries

The package is published to two registries on every release:

Registry	Package
npm	council-mcp
GitHub Packages	@iamvirul/council-mcp

---

Usage Examples

Trivial - formatting

"Use The Council to format this JSON into a clean, human-readable structure."

Routes to the Aide (Haiku 4.5), then the Supervisor reviews the output. Fast and cheap.

Complex - architecture design

"Use The Council to design a microservices architecture for my e-commerce app."

Routes to the Chancellor (Opus 4.6) for analysis and planning. Each plan step runs through the Executor (Sonnet 4.6), which delegates simple sub-tasks to the Aide. The Supervisor reviews each Executor step and Aide task before results are aggregated.

Review supervisor flags

After running orchestrate, call get_supervisor_verdicts with the session ID.

{ "session_id": "<uuid>", "flagged_only": true }

Returns only the outputs the Supervisor flagged, with specific issues and recommendations.

Direct consultation - risk analysis

"Consult the Chancellor about the risks in migrating our API from REST to GraphQL."

Calls consult_chancellor directly, skipping orchestration. Returns a structured ChancellorResponse with analysis, risks[], assumptions[], success_metrics[], and recommendations[].

---

Session Lifecycle

Use get_council_state at any point to inspect a session. Each session tracks:

• Phase (planning / executing / complete / failed)
• Chancellor plan (if invoked)
• Executor step results
• Aide task results
• Supervisor verdicts (one per Executor step and Aide task)
• Metrics: total agent calls, agents invoked, duration, caveman mode, eval retries

---

Development

git clone https://github.com/iamvirul/the-council.git
cd the-council

npm install

npm run dev         # run with tsx, no compile step
npm run build       # compile TypeScript to dist/
npm run type-check  # TypeScript check only
npm test            # run tests with vitest
npm run test:watch  # vitest watch mode

Project structure

src/
  domain/           # Pure types, constants, error classes - no I/O
    models/         # types.ts, schemas.ts - response shapes and Zod validators
    constants/      # index.ts - model IDs, MAX_TURNS, system prompts
  application/      # Agent invocation and orchestration logic
    orchestrator/   # Complexity assessment + full orchestration flow
    chancellor/     # Chancellor agent wrapper
    executor/       # Executor agent wrapper
    aide/           # Aide agent wrapper
    supervisor/     # Supervisor agent wrapper (active quality gate with eval loop)
  infra/            # External dependencies
    agent-sdk/      # runner.ts (subprocess), parse.ts (JSON extractor), run-with-validation.ts (retry wrapper)
    config/         # caveman.ts (token compression), eval.ts (Supervisor retry budget)
    state/          # Session store: memory / file / SQLite backends
    logging/        # pino structured logger (stderr only)
  mcp/
    server/         # MCP server setup, tool registration, lifecycle
    tools/          # Zod schemas for all tool inputs
tests/
  unit/             # Fast isolated tests: config, schemas, stores, agent invokers, orchestrator
  integration/      # Real filesystem tests for FileStore and SQLiteStore

---

Release

1. Bump version in package.json.
2. Update CHANGELOG.md - move Unreleased entries under the new version heading.
3. Tag and push: git tag vX.Y.Z && git push origin vX.Y.Z
4. GitHub Actions builds, creates a GitHub Release, and publishes to npm and GitHub Packages.

To enable npm publishing, add your NPM_TOKEN as a repository secret under Settings -> Secrets and variables -> Actions.

---

License

MIT - see LICENSE.