Roundtable CLI

One question. Multiple views. One answer.

Roundtable sits your local AI tools at the same table — Codex, Claude, Gemini, and Cursor — and lets them challenge each other on your question. A leader keeps the conversation moving. You get a saved markdown report with the final synthesis.

Good for launch plans, architecture reviews, product ideas, and anything where one model’s first reply isn’t enough.

What you need

• Node.js 22.6 or newer
• npm or pnpm — to install the CLI (pnpm required only for from-source development)
• At least one local AI CLI on your PATH:
  • codex
  • claude
  • gemini
  • agent (Cursor — install with curl https://cursor.com/install -fsS | bash)

Install/Update

From npm:

npm install -g roundtable-cli@latest

With pnpm:

pnpm add -g roundtable-cli@latest

Run once without a global install:

npx roundtable-cli "your question"

From source

If you're developing Roundtable or running from a clone:

corepack pnpm install
corepack pnpm run build
corepack pnpm start "your question"

Quick start

1. Run your first roundtable

roundtable "Review this launch plan and flag the biggest risks"

The first time you run roundtable, a setup wizard opens. Pick your participants, models, and a leader. Settings are saved to ~/.config/roundtable/debate.json when installed globally, or ./config/debate.json in the project directory you run from.

2. Read the report

When the run finishes, the terminal shows two paths:

• Report — YYYY-MM-DD-topic.md in the current directory (read this)
• Logs — detailed session log for debugging

The live terminal shows progress, not full model replies. Open the markdown report for the full debate and final answer.

Attach reference files

Reference any local file path in your question with @:

roundtable "Review this plan @./docs/plan.md"
roundtable "Compare these notes @/tmp/brief.md"

Examples

roundtable "Review this launch plan and identify the biggest risks"
roundtable "Help improve this architecture proposal @proposal.md"
roundtable "Generate competing product strategy options"
roundtable "Critique this implementation plan" --leader=claude --limit=6
roundtable "Compare these ideas" --clis=codex,gemini --human-in-the-loop=false
roundtable "Stress-test this design" --single-cli=claude:proposer,critic,verifier
roundtable --help

First-run setup (what the wizard asks)

1. How many participants? — Each gets a CLI, model, and role.
2. For each participant — Pick CLI → model → role (Peer, Critic, Proposer, etc.).
3. Leader — Which CLI runs the roundtable and writes the final synthesis.
4. Question limit — How many debate rounds to allow (default 5). Clarifying questions do not count.
5. Human in the loop — If on, the leader may ask you one clarification question mid-run.

To reconfigure, run roundtable again and choose Setup from scratch, or delete config/debate.json.

Manual config (non-interactive environments)

If the wizard cannot run (no TTY), copy config/debate.example.json to config/debate.json and edit it. See the Configuration section below.

Roles

Each participant gets a role that shapes how they respond. The setup wizard lets you pick one per actor; you can also assign roles per run with --actors=claude:proposer,gemini:critic.

Built-in roles

| Role | What it does | | -------------- | ------------------------------------------------------------------------------------------------------------ | | Peer | Neutral challenger. Improves reasoning and engages with others’ strongest points without claiming authority. | | Proposer | Commits to a clear, defensible position and defends it with explicit reasoning. | | Critic | Breaks the strongest argument on the table — gaps, edge cases, counterexamples, unsupported assumptions. | | Verifier | Audits factual claims. Marks assertions as verified, unverified, likely wrong, or cannot assess. | | Contrarian | Steelmans the least popular or most dismissed position the group may be overlooking. | | Pragmatist | Translates abstract debate into feasibility, cost, failure modes, and concrete next steps. |

Custom roles

During setup you can define a custom role with your own behavioral instructions. Saved custom roles are stored in config/debate.json under customRoles and appear in the role picker for later participants. Custom role ids use lowercase letters, numbers, and hyphens (max 32 characters).

Options

| Flag | What it does | | ---------------------------------------- | ---------------------------------------------------------------------------- | | --help, -h | Show usage, flags, and examples | | --clis=codex,claude,gemini,cursor | Who participates this run (default role: peer) | | --actors=claude:proposer,gemini:critic | Assign a role to each CLI this run | | --single-cli=claude:proposer,critic | Multiple roles on one CLI (single-cli mode); leader must match that CLI | | --leader=codex | Who leads (codex, claude, gemini, cursor) | | --limit=12 | Max debate questions (clarifications excluded) | | --human-in-the-loop=true | Leader may ask you one question mid-run | | --claude-model=claude-opus-4-6 | Claude model (default from config or built-in default) | | --codex-model=gpt-5.5 | Codex model | | --gemini-model=gemini-3-flash-preview | Gemini model | | --cursor-model=auto | Cursor model |

Short forms like -limit=6 also work. Use --name=value or --name value.

Configuration

Settings live in config/debate.json:

• Global install (npm install -g roundtable-cli) — ~/.config/roundtable/debate.json, shared across projects.
• Project override — if ./config/debate.json exists in the directory you run from, that file is used instead.
• From source — ./config/debate.json in the repo you cloned (unless a user config already exists at ~/.config/roundtable/debate.json).

Debate reports and logs are always written to the directory you run roundtable from, not the config location.

An annotated template is at config/debate.example.json.

| Field | Meaning | | ----- | ------- | | actors[] | Each participant: cli, role, optional model | | leader | CLI id that orchestrates (must match an actor CLI) | | limit | Max leader-issued debate questions | | humanInTheLoop | Whether the leader may pause once for your input | | models | Default model per CLI (first model per CLI wins when duplicated) | | debateMode | Inferred: multi-cli or single-cli — do not set manually | | customRoles | Optional map of custom role id → behavior text |

Config id cursor refers to the agent command on your PATH.

What’s in the report

Each run saves a markdown file in the current directory with:

• Your original question
• A running summary of the discussion
• Each round’s questions and answers
• The final synthesis
• Any failures (one model failing does not stop the others)

Contributing & internals

New contributors: start with ONBOARDING.md. For architecture, debate engine rules, adapter details, and development setup, see AGENTS.md.