agent-roundtable
# agent-roundtable
**Agents talk it out at the table, then go heads-down.**
An MCP server for multi-agent collaboration across six LLM providers: discuss, challenge and agree on a plan, then execute a contract with parallel workers, budgets and human oversight.
Runs locally over stdio with Claude Code or any MCP client. Requires Node 22.19+.
## Install and register with Claude Code
```sh
npm install -g agent-roundtable
claude mcp add --scope user roundtable \
-e ROUNDTABLE_AGENTS_DIR="$HOME/my-project/.claude/agents" \
-- roundtable mcp
claude mcp list # roundtable should show as connected
```
`roundtable mcp` starts the orchestrator server, the same as running the binary with no arguments. Without the global install, use `-- npx -y agent-roundtable@2.0.0` or `-- node /absolute/path/to/dist/index.js` (a source checkout). `--scope user` makes it available in every project; leave it out (or use `--scope project`) to register it for one project only. Then ask Claude Code to "list the roundtable tools": you should see the 43 [tools](#tools), named `mcp__roundtable__<tool>`.
Create personas in that directory or install the [starter pack](examples/starter-pack/) with `roundtable agents starter`. Set keys for the [providers](docs/providers.md) you use; local meetings use your Claude CLI login. For source installs, `.env`, `add-json` and project `.mcp.json` registration, see [getting started](docs/getting-started.md) and [configuration](docs/configuration.md). After a rebuild, reconnect with `/mcp`.
## Other ways to install
A Docker image recipe, a Claude Code plugin and an MCP registry listing are described in [distribution](docs/distribution.md). Until the package is published to npm, the `npx` and plugin paths do not resolve.
## Modes
### At the table
Ask in chat; the host calls the tools and keeps session ids for follow-ups.
| Format | What it does | Example prompt |
| --- | --- | --- |
| [Meeting](docs/modes/meetings.md) | Talk with one persona on a chosen provider/model. | “Start a meeting via roundtable with cfo about our Q3 budget.” |
| [Local meeting](docs/modes/meetings.md#local-meetings) | Talk with a persona through your installed Claude CLI and login. | “Start a local meeting with product-lead about onboarding.” |
| [Collaboration: collaborate](docs/modes/collaborations.md) | Personas take turns building a shared idea. | “Have cfo and product-lead collaborate on launch priorities for three rounds.” |
| [Collaboration: debate](docs/modes/collaborations.md#formats) | One proponent faces challengers. | “Have cfo defend our pricing plan against skeptic in a roundtable debate.” |
| [Collaboration: waffle-house](docs/modes/collaborations.md#formats) | A defender refines an idea through repeated attacks and rebuttals. | “Run a two-round waffle-house: product-lead defends one-click checkout against cfo and skeptic.” |
| [Collaboration: conversation](docs/modes/collaborations.md#conversation-mode) | Informal colleague chat with an optional theme and private grounding. | “Let cfo and product-lead chat about the launch in conversation mode.” |
| [Ultraplan](docs/modes/ultraplan.md) | Collect input, review revisions and record sign-offs on a plan. | “Ultraplan the launch with product-lead, cfo and skeptic; show the final document verbatim.” |
| [Agent workshops](docs/modes/agent-workshops.md) | Specialists create or improve an agent and reusable skills. | “Have cfo and skeptic create a budget agent, then improve product-lead's escalation rules; preview both.” |
| [Prototype mode](docs/modes/prototype-mode.md) | Show ephemeral proposals on a local prototype board for assessment. | “Run a prototype collaboration on checkout with product-lead and skeptic.” |
| [Casting Call](docs/modes/casting-call.md) | Audition personas for a brief; find redundancy, gaps and a recommended cast. | “Cast our personas for a bounded-memory queue module.” |
| [Duel](docs/modes/duel.md) | Two teams build competing artifacts (a page, code, a diagram or a document); judges assess them; dissents are recorded. | “Run a duel on a rate limiter module with architect and engineer against pragmatist and reviewer, judged by security-lead.” |
| [Public sessions](docs/modes/public-sessions.md) | Mirror an explicitly public session to ntfy or a webhook. | “Make that pricing debate public and give me the viewing link.” |
| Terminal command | Purpose |
| --- | --- |
| [`roundtable up`, `doctor`](docs/getting-started.md#quick-start-roundtable-up) | Set up, check your install (keys, git, Docker, Chrome) and start the local service. |
| [`roundtable cast`](docs/modes/casting-call.md) | Audition personas and recommend a cast for a brief. |
| [`roundtable duel`](docs/modes/duel.md) | Two teams build competing artifacts; judges assess them; dissents are recorded. |
| [`roundtable debate`, `waffle`, `meeting`](docs/table-cli.md) | Stream a discussion with per-seat models and spend. |
| [`roundtable preview`](docs/previews.md) | Preview a task's or prototype's dev server live in a locked-down container on `127.0.0.1`. |
| [`roundtable config`](docs/configuration.md#saved-cli-settings-and-env-files) | Save env-file and persona-directory settings; show set/unset status. |
| [`roundtable agents`](docs/agents-library.md) | Browse and import personas, install the starter pack, or open the library drop zone. |
### Heads-down
[Heads-down runs](docs/heads-down.md) execute an agreed, frozen contract in parallel task worktrees with leases, checks, a watchdog and escalations. Example: “Execute the approved contract with a $20 budget and a dashboard; keep me posted here.” See the [example contract](examples/contract.example.json).
[Postmortem mode](docs/modes/postmortem.md) is opt-in per project: while testing sends fixers back the orchestrator keeps a draft of every finding, then the agents that did the work meet it (the human has no seat) and leave lessons that are read before the next plan. Example: “Turn on postmortem meetings for this project.”
## Tools
**43 tools on the orchestrator server; 8 on worker servers.** The seven execution worker tools appear in both; the orchestrator's copies also require `execution_id` and `agent_token`. Dissent filing is also available on both servers. The table follows the registered definitions in `src/tools/*.ts`; [full arguments and examples](docs/tools.md).
| Group | Tool | Purpose |
| --- | --- | --- |
| Meetings | [`start_meeting`](docs/tools.md#start_meeting) | Start a conversation with one persona. |
| Meetings | [`say`](docs/tools.md#say) | Send a message in an API meeting. |
| Meetings | [`end_meeting`](docs/tools.md#end_meeting) | End an API meeting, optionally with a summary. |
| Meetings | [`list_meetings`](docs/tools.md#list_meetings) | List active API meetings. |
| Local meetings | [`start_local_meeting`](docs/tools.md#start_local_meeting) | Start a persona meeting on the local Claude CLI. |
| Local meetings | [`say_local`](docs/tools.md#say_local) | Send a message in a local meeting. |
| Local meetings | [`end_local_meeting`](docs/tools.md#end_local_meeting) | End a local meeting, optionally with a summary. |
| Local meetings | [`list_local_meetings`](docs/tools.md#list_local_meetings) | List active local meetings. |
| Collaborations | [`start_collaboration`](docs/tools.md#start_collaboration) | Start a discussion between two or more personas. |
| Collaborations | [`continue_collaboration`](docs/tools.md#continue_collaboration) | Run additional rounds. |
| Collaborations | [`nudge_collaboration`](docs/tools.md#nudge_collaboration) | Inject guidance without consuming an agent turn. |
| Collaborations | [`pause_collaboration`](docs/tools.md#pause_collaboration) | Pause after the current turn. |
| Collaborations | [`end_collaboration`](docs/tools.md#end_collaboration) | End a discussion and return its transcript and optional summary. |
| Collaborations | [`get_collaboration_transcript`](docs/tools.md#get_collaboration_transcript) | Read a discussion without ending it. |
| Collaborations | [`list_collaborations`](docs/tools.md#list_collaborations) | List active collaborations. |
| Casting Call | [`casting_call`](docs/tools.md#casting_call) | Audition personas and recommend a cast for any brief. |
| Duel | [`start_duel`](docs/tools.md#start_duel) | Run a duel: two teams build competing artifacts, judges assess them, dissents are recorded. |
| Ultraplan | [`start_ultraplan`](docs/tools.md#start_ultraplan) | Collect input and begin a reviewed plan. |
| Ultraplan | [`submit_plan`](docs/tools.md#submit_plan) | Review a full plan version or collect final sign-offs. |
| Ultraplan | [`end_ultraplan`](docs/tools.md#end_ultraplan) | Close a plan without sign-offs. |
| Agent workshops | [`create_agent`](docs/tools.md#create_agent) | Have specialists design and optionally save a new agent. |
| Agent workshops | [`improve_agent`](docs/tools.md#improve_agent) | Review and optionally update an agent with a backup. |
| Contracts | [`propose_contract`](docs/tools.md#propose_contract) | Turn a plan into a draft execution contract. |
| Contracts | [`amend_contract`](docs/tools.md#amend_contract) | Apply a versioned contract merge patch. |
| Contracts | [`freeze_contract`](docs/tools.md#freeze_contract) | Freeze the current contract after consent. |
| Contracts (both servers) | [`file_dissent`](docs/tools.md#file_dissent) | File, complete or explicitly excuse a draft dissent. |
| Contracts | [`score_dissent`](docs/tools.md#score_dissent) | Record an advisory assessment of a dissent's prediction. |
| Runs | [`execute`](docs/tools.md#execute) | Preflight and start an authorized frozen contract. |
| Runs | [`execution_status`](docs/tools.md#execution_status) | Report progress, blockers, budget and context. |
| Runs | [`control_execution`](docs/tools.md#control_execution) | Pause, resume, steer, abort or purge a run; stop an agent; write a handoff. |
| Runs | [`resolve_escalation`](docs/tools.md#resolve_escalation) | Decide, huddle, retry, reassign or amend after an escalation. |
| Runs | [`join_execution`](docs/tools.md#join_execution) | Register an external worker and return its token once. |
| Postmortem | [`postmortem`](docs/tools.md#postmortem) | Opt in per project, keep the running draft of findings, read lessons and records. |
| Postmortem | [`hold_postmortem`](docs/tools.md#hold_postmortem) | Hold the blameless meeting after the fixes, then conclude it with accepted artifacts. |
| Workers (both servers) | [`read_blackboard`](docs/tools.md#read_blackboard) | Read shared run state and your inbox. |
| Workers (both servers) | [`claim_task`](docs/tools.md#claim_task) | Claim or release an external worker task. |
| Workers (both servers) | [`lease`](docs/tools.md#lease) | Request or release path leases. |
| Workers (both servers) | [`post_update`](docs/tools.md#post_update) | Post progress, notes, interfaces, needs, acknowledgements or an external worker's usage. |
| Workers (both servers) | [`run_command`](docs/tools.md#run_command) | Run structured argv or a contract check in the sandbox. |
| Workers (both servers) | [`submit_work`](docs/tools.md#submit_work) | Checkpoint or submit leased changes for checks and merging. |
| Workers (both servers) | [`escalate`](docs/tools.md#escalate) | Raise a blocker, question, conflict or emergency. |
| Usage | [`usage`](docs/tools.md#usage) | Report who is using what, stop an agent, write a handoff. |
| Completion | [`chat_completion`](docs/tools.md#chat_completion) | Call any of the six text providers directly. |
| Diagnostics | [`debug_env`](docs/tools.md#debug_env) | Inspect configuration and key presence without key values. |
## CLI
No arguments starts the orchestrator MCP server. The binary has **15 subcommands**, plus **7 table commands** that run at the table from a terminal (`cast`, `duel`, `debate`, `waffle`, `meeting`, `config`, `secrets`). Both are documented in the [CLI reference](docs/cli.md); `roundtable` is a second name for the same binary.
| Subcommand | Purpose |
| --- | --- |
| `mcp` | Start an orchestrator or token-bound worker stdio server. |
| `hook pre-tool-use` | Check worker file access and leases using stdin hook JSON. |
| `run <exe>` | Run or recover a heads-down runner. |
| `watch <exe> --as <name> [--timeout-min N]` | Wait for one orchestrator wake, printing JSON. |
| `status <exe> [--json]` | Inspect a run's tasks, budget and health. |
| `verify <exe> [--json]` | Verify execution and audit chains. |
| `purge <exe> --confirm` | Delete a finished run's worktrees, branches and log. |
| `statusline [--agents N] [--plain] [--no-host]` | A Claude Code status line with the host and the roundtable's spend. |
| `usage [--json] [--watch]` | Who is using what, on which platform, measured or estimated. |
| `stop <agent> [--execution <exe> \| --session <id>] [--reason <text>]` | Stop one agent, heads-down or at the table. |
| `serve` / `notify` | Keep runs alive, browse the private index and configure [check-ins](docs/long-running.md). |
| `runtimes [--json]` | Detect installed [CLI runtimes](docs/runtimes.md). |
| [`agents [--json]`](docs/agents-library.md) | List or import personas, install the starter pack, open the library. |
| `help` | Print usage. |
| `cast`, `duel`, `debate`, `waffle`, `meeting`, `config`, `secrets` | Table commands: see [at the table from the terminal](docs/table-cli.md). |
## Docs
- [Getting started and registration](docs/getting-started.md)
- [Distribution](docs/distribution.md): Docker, Claude Code plugin, MCP registry and the owner release checklist
- [Mode guides](docs/modes/meetings.md): [collaborations](docs/modes/collaborations.md), [ultraplan](docs/modes/ultraplan.md), [agent workshops](docs/modes/agent-workshops.md), [prototypes](docs/modes/prototype-mode.md), [public sessions](docs/modes/public-sessions.md), [postmortems](docs/modes/postmortem.md)
- [Heads-down user guide](docs/heads-down.md) and [design specification](docs/design/heads-down.md); [postmortem design specification](docs/design/postmortem.md)
- [Usage visibility](docs/usage.md): the status line, the usage report, the dashboard Usage page and stopping an agent
- [Dissents and tripwires](docs/dissents.md)
- [At the table from the terminal](docs/table-cli.md): `duel`, `debate`, `waffle`, `meeting`, per-seat models and replay
- [Duel](docs/modes/duel.md) and the [demo recording script](docs/demo.md)
- [Tool reference](docs/tools.md) and [CLI reference](docs/cli.md)
- [CLI runtimes at the table](docs/runtimes.md): installed agents alongside API providers
- [Secrets broker](docs/secrets.md) and [connectors](docs/connectors.md) (workers and seats at the table)
- [Configuration](docs/configuration.md), [providers](docs/providers.md) and [provider judgment](docs/providers.md#provider-judgment)
- [Agent personas and skills](docs/agents.md) and [session archives](docs/sessions.md)
- [Changelog](CHANGELOG.md), [threat model](docs/THREAT_MODEL.md), [security controls](docs/SECURITY_CONTROLS.md)
## Security
Read the [security policy and private reporting instructions](SECURITY.md), and the [October 2026 audit](docs/security/audit-2026-10.md).
## Contributing
Build and run `npm test` before a pull request. See [contributing](docs/contributing.md) for test isolation and checks.
## License
[Apache License 2.0](LICENSE); see also [NOTICE](NOTICE).
TDQS
Scored across 49 tools
The descriptions are extraordinarily detailed and usually spell out exactly when to use each tool (e.g. pause is resumed with nudge_collaboration, not continue_collaboration), which rescues many borderline pairs. However there are near-duplicate families that differ only by billing path: start_meeting vs start_local_meeting, say vs say_local, end_meeting vs end_local_meeting, list_meetings vs list_local_meetings, plus several sibling session starters (start_collaboration, start_duel, start_ultraplan, casting_call, chat_completion) that an agent can easily mispick. postmortem vs hold_postmortem and execute vs execution_status vs control_execution also require reading long text to separate.
The dominant pattern is snake_case verb_noun (start_meeting, end_collaboration, submit_work, resolve_escalation), which is readable and mostly predictable. But the set mixes pure-verb tools (execute, escalate, lease), noun-only tools (usage, postmortem, chat_completion, casting_call), and an inconsistent _local suffix convention that applies to only four of the meeting tools rather than a consistent scope qualifier.
49 tools is very heavy for a single MCP surface and far exceeds the 3-15 sweet spot. The domains are genuinely broad (chat, meetings, collaborations, ultraplans, contracts, executions, blackboard/worker ops, previews, usage, agents, postmortems), but the near-duplicate local/remote meeting quadruplets show the count is inflated by parallel variants that could be one tool with a mode flag.
Coverage is unusually thorough: full contract lifecycle (propose/amend/freeze/execute/status/control), worker primitives (claim, lease, post, run, submit, escalate, spawn/await), previews, usage accounting, and postmortem remediation all have tools. Minor gaps exist — no listing/deletion of created agents, no way to inspect a duel afterwards beyond the inline result, and no delete/discard for archived sessions — but these are workable around.