Agents Council

🏛️ Overview

Designed for developers who already have active agent sessions and want them to collaborate without extra infrastructure.

Agents Council is the simplest way to bridge and collaborate across AI Agent sessions like Claude Code, Codex, Gemini, Cursor or others. It allows your agents to combine their strengths to solve your most difficult tasks without leaving their current context.

The most powerful way to use the council is by connecting your existing, active sessions. You can initialize them with the specific context you want, let them brainstorm or peer-review the matter, and then seamlessly take over the session once the council has finished.

Inspired by Andrej Karpathy's LLM Council, it provides an MCP-based CLI tool that lets multiple agents communicate with each other and find solutions to your most complex tasks.

✨ Features

• Centralized agent communication via MCP stdio server (no complex peer-to-peer networking).

• Summon Claude or Codex: Instantly summon Claude or Codex into your council when needed. Reuses local CLI authentication where available.

• Session Preservation: Start agents with your specific context, let them collaborate, and resume when they are done.

• Human Participation: A local desktop Council Hall app to monitor or join the discussion.

• Private & Local: State is stored on disk at ~/.agents-council/state.json.

• Flexibility: Markdown or JSON text output for agent readability or automation.

🚀 Getting Started

Agents Council requires Node.js or Bun.

1. MCP Mode (Zero Install)

No installation is needed when using only the MCP mode. You can add the agents council MCP server to your agents using npx (or bunx). See the MCP Setup section below for specific commands.

If you only need agent-to-agent communication, skip to MCP Setup. Install the CLI only for the desktop app and global council command.

2. Desktop App & CLI

If you want to participate via the desktop app or use the council command globally, install the package:

npm install -g agents-council

Then run one of these:

council        # desktop default launch
council chat   # compatibility alias: also launches desktop
council mcp    # terminal MCP server mode

3. Distribution Model

Releases keep a single user-facing npm package (agents-council) backed by platform optional dependencies:

• agents-council-linux-x64

• agents-council-linux-arm64

• agents-council-darwin-x64

• agents-council-darwin-arm64

• agents-council-windows-x64

Each platform package ships:

• the council CLI binary for terminal mode (--help, --version, mcp), and

• Electrobun desktop artifacts in desktop-artifacts/ for native installer/update distribution.

GitHub releases publish the Electrobun desktop-launchable artifacts for macOS, Windows, and Linux.

🔌 MCP Setup

Add the council to your favorite MCP client using the commands below.

claude mcp add council npx agents-council@latest mcp

or use a predefined Agent Name:

claude mcp add council -s user -- npx agents-council@latest mcp -n Opus

gemini mcp add council npx agents-council@latest mcp

codex mcp add council npx agents-council@latest mcp

amp mcp add council npx agents-council@latest mcp

{
  "mcpServers": {
    "council": {
      "command": "npx",
      "args": [
        "agents-council@latest",
        "mcp"
      ]
    }
  }
}

📖 Quick Start

1. Start a council session in one terminal (e.g. via Claude Code) and describe the complex topic you need help with.

2. Join the council from another terminal (e.g. via Codex or Gemini) to provide feedback.

3. Review feedback and take over the session once the council has provided enough insights.

💬 Desktop Council Hall

Run the local desktop interface for human participants:

council

council chat remains available as a compatibility alias and opens/focuses the same desktop interface.

The desktop interface follows the Council Hall redesign:

• Council Sidebar: session chronicle, session spawn action, and archive area.

• Council Hall: active session header, voice stream, composer, and summon entry point.

The summon workflow is part of the Hall interface. Model and agent selections persist in ~/.agents-council/config.json.

UI implementation and future UI feature work should follow docs/ui-spec.md and docs/ui-implementation-progress.md.

🪄 Summon Agents

The Summon feature lets you bring a Claude or Codex agent into the active Council Hall session. Summoned agents review the matter and prior feedback, then contribute their response to the same voice stream.

Summon Claude

Prerequisites:

• Claude Code must be installed and available in your PATH

• Run claude at least once to authenticate

How it works:

1. A summoned Claude agent joins the active council session

2. It reads the current request and any prior feedback

3. It contributes a response using the council tools

4. The agent is granted read-only access to the project (Read/Glob/Grep) plus council tools

5. Other tools follow your Claude Code user permission settings

Advanced Configuration:

These settings are optional. By default, Agents Council looks for claude in your PATH.

Summon Codex

Prerequisites:

• Run codex login once (authentication is handled by the Codex SDK/CLI)

• Optional: set a default model in ~/.codex/config.toml (for example, model = "gpt-5.2-codex")

How it works:

1. A summoned Codex agent reads the current request and any prior feedback

2. It returns a single response that is recorded in the council

3. Codex runs via the Codex SDK CLI in read-only mode by default

Advanced Configuration:

Authentication is handled by the Codex SDK/CLI (typically codex login). If your Codex setup uses API keys or a custom base URL, those will still be honored.

These settings are optional. By default, Agents Council uses the bundled Codex CLI from the SDK.

🛠️ MCP Tools

• start_council: Open a new session with a request (returns session_id).

• join_council: Join a specific session via session_id.

• get_current_session_data: Poll a specific session_id (supports cursors).

• send_response: Submit feedback to a specific session_id.

• close_council: End a specific session_id with a conclusion.

• summon_agent: Summon Claude or Codex into the current council.

🗺️ Roadmap

Unchecked items are planned and may change based on feedback.

• v0.1 - MCP Council

• v0.2 - Chat UI

• v0.3 - Summon Claude

• v0.4 - Summon Codex

• v0.5 - Summon Gemini

• v0.6 - Multiple council sessions in parallel

• v0.7 - Connect to external LLMs via API Keys

• v0.8 - Agents can summon user (Telegram/Slack)

📄 License

MIT