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 agent produces output, the Supervisor (Haiku) reviews it for quality and flags any issues before results surface to the caller.

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.

Agent Roles

The Supervisor is advisory only — it annotates and flags, never blocks. If the Supervisor errors, orchestration continues and a warning is logged.

Orchestration Flow

MCP Tools

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.

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.

Registries

The package is published to two registries on every release:

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

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 (non-blocking quality review)
  infra/            # External dependencies
    agent-sdk/      # runner.ts - spawns claude CLI subprocess for each agent
    state/          # In-process session state store (LRU, 500 session cap)
    logging/        # pino structured logger (stderr only)
  mcp/
    server/         # MCP server setup, tool registration, lifecycle
    tools/          # Zod schemas for all tool inputs

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.