conclave

A small MCP server that lets one AI orchestrate a council of others. Claude convenes Codex and Gemini via their CLIs, asks them, paraphrases responses back into the discussion, and pushes toward consensus — like cardinals in a papal conclave deliberating until white smoke.

   you
    ↓
   Claude  (orchestrator)
    ├── ask_codex   → spawns `codex` CLI
    └── ask_gemini  → spawns `gemini` CLI

Why

You probably have ChatGPT Plus and Gemini Pro subscriptions sitting around. Their CLIs already authenticate against your account. Why pay for separate API keys to hear what they think?

conclave is a thin MCP (Model Context Protocol) server that exposes each CLI as a tool. Plug it into Claude Code (or any MCP client) and the orchestrator can poll the council, paraphrase responses, run multiple rounds of deliberation, and synthesize a final answer.

Prerequisites

Before you start, make sure you have:

• Node.js ≥ 18 — nodejs.org (LTS is fine).
• An OpenAI account with access to the Codex CLI (any ChatGPT plan that supports Codex login).
• A Google account with access to the Gemini CLI (a free Google account works; paid Gemini plans get higher limits).
• Claude Code installed and working (claude --version should print a version).
• Git, for cloning the repo.

Platform support: Developed and tested on Windows. The server is written to be cross-platform and should work on macOS and Linux, but those haven't been runtime-tested yet. If you hit a snag, please open an issue.

Installation

1. Install the Codex CLI and log in

npm install -g @openai/codex
codex

The first run opens a browser to log in with your OpenAI account. Sign in, close the tab when done, and exit codex (Ctrl+C or type /exit). Verify:

codex --version

2. Install the Gemini CLI and log in

npm install -g @google/gemini-cli
gemini

Same idea: first run prompts a browser login with your Google account. Sign in, exit, verify:

gemini --version

3. Install the conclave plugin

Since v0.5.0 conclave is a Claude Code plugin — the MCP server, slash command, and helpers all install in one shot:

claude plugin add github:cogspro1234/conclave

Then restart Claude Code so the MCP server and slash command load.

4. Verify

Inside Claude Code:

claude mcp list

You should see conclave: ✓ Connected. Then try the slash command:

/conclave:convene say hello in one short sentence

Claude commits to its own initial position, calls Codex and Gemini in parallel, runs a rebuttal round, and synthesizes a verdict. If you see three distinct voices in the synthesis, you're done.

Manual install (advanced / pre-v0.5.0)

If you don't want to use Claude Code's plugin system — or you're on a version of Claude Code without it — clone the repo and wire the components manually:

<details> <summary>Click to expand manual install instructions</summary>

git clone https://github.com/cogspro1234/conclave.git
cd conclave
npm install

Register the MCP server (use --scope user so it works from every project):

# macOS / Linux
claude mcp add --scope user conclave -- node "$(pwd)/src/server.js"

# Windows (Git Bash)
claude mcp add --scope user conclave -- node "$(pwd -W)/src/server.js"

# Windows (PowerShell)
claude mcp add --scope user conclave -- node "$((Get-Location).Path -replace '\\','/')/src/server.js"

Copy the slash command into user scope:

# macOS / Linux
mkdir -p ~/.claude/commands && cp commands/convene.md ~/.claude/commands/

# Windows (Git Bash)
mkdir -p "$USERPROFILE/.claude/commands" && cp commands/convene.md "$USERPROFILE/.claude/commands/"

# Windows (PowerShell)
New-Item -ItemType Directory -Force "$env:USERPROFILE\.claude\commands" | Out-Null; Copy-Item commands\convene.md "$env:USERPROFILE\.claude\commands\"

Restart Claude Code, then run claude mcp list to verify.

</details>

Usage

The recommended way is the /conclave:convene slash command (plugin install):

/conclave:convene should we use Postgres or SQLite for this side project?

(If you used the manual install path, the command is just /convene — no namespace prefix since it lives directly at user scope.)

Claude commits to its own initial position, then calls ask_codex and ask_gemini in parallel, paraphrases each response back to the other for a rebuttal round, then synthesizes a final answer that surfaces real disagreements rather than papering over them.

Claude may also invoke the conclave when "conclave" comes up naturally in conversation (e.g. "let's take this to the conclave") — the slash command is just the explicit, documented entry point.

Three voices, not two

Since v0.4.0, the conclave is genuinely three-way — Claude (the orchestrator) commits to its own initial position, then deliberates alongside Codex and Gemini, revising as it hears them out. The synthesis names who held which view rather than presenting a moderator's verdict from above.

Flags

You can prefix the topic with optional flags (any order, can combine):

/conclave:convene --strong is this caching strategy correct?
/conclave:convene --fast quick sanity check on this regex
/conclave:convene --silent should we drop SQLite for Postgres
/conclave:convene --strong --silent fundamental architecture call: monolith or services
/conclave:convene just deliberate normally on whether to add a CI step

Flag	Effect
--strong	Sends tier: "strong" — server picks model per config, defaults to Codex gpt-5.5 and Gemini gemini-3-flash-preview.
--fast	Sends tier: "fast" — defaults to Codex gpt-5.4-mini and Gemini gemini-2.5-flash-lite.
--silent	Suppress all interim narration. Tool calls still happen; you only see the final verdict.
--rounds N	Number of deliberation rounds. 1 = initial positions only, no rebuttal. 2 = default (initial + rebuttal). 3 = adds a final round where each voice gives its closing position after seeing the rebuttal.
--without-codex	Skip Codex entirely. Run as a 2-way deliberation (Claude + Gemini).
--without-gemini	Skip Gemini entirely. Run as a 2-way deliberation (Claude + Codex).
(no flags)	2 rounds, both council members, server's configured default models, full transcript shown.

If a council member fails mid-deliberation (auth expired, quota hit, network), the conclave drops that voice and continues with the rest, noting the dropout in the synthesis — the deliberation no longer crashes when one CLI is unavailable.

Natural-language phrasing works too — /conclave en güçlü modellerle: ..., /conclave hızlı bir check: ..., /conclave kararı doğrudan ver: ..., /conclave Codex'siz: ..., /conclave 3 tur: ....

To change which model each tier resolves to (e.g. you have ChatGPT Plus but no Gemini Pro and want --strong to stay on a free Gemini model), run the interactive picker: npx conclave-config. It writes ~/.conclave.json and the MCP server reads it on startup — restart Claude Code to apply.

Configuration

Picking models per tier (~/.conclave.json)

Two ways to set which model --strong, --fast, and the no-flag default resolve to for each provider:

Inside Claude Code (recommended for plugin install):

/conclave:config

Walks you through 6 picks (Codex × {default, strong, fast}, Gemini × {default, strong, fast}) using clickable choice prompts — pick from the preset list, or pick "Other" and type a custom model name.

From the terminal:

npx conclave-config

Same picker, but as an interactive Node script. Useful for the manual install path or if you'd rather configure outside the chat.

Either way, the result lands in ~/.conclave.json:

{
  "codex":  { "default": "gpt-5.4", "strong": "gpt-5.5",          "fast": "gpt-5.4-mini" },
  "gemini": { "default": null,      "strong": "gemini-2.5-flash", "fast": "gemini-2.5-flash-lite" }
}

The MCP server reads this on startup — restart Claude Code after changes. Resolution order per call: explicit model arg → config tier → built-in fallback tier → config default → CONCLAVE_*_MODEL env var → CLI's own default.

Environment variables

Variable	Default	Purpose
CONCLAVE_CODEX_CMD	codex.cmd on Windows, codex else	Path/name of the Codex CLI binary.
CONCLAVE_GEMINI_CMD	gemini.cmd on Windows, gemini else	Path/name of the Gemini CLI binary.
CONCLAVE_TIMEOUT_MS	300000 (5 min)	Per-call timeout. Long deliberations may need more.
CONCLAVE_CODEX_MODEL	(unset → CLI default)	Last-resort default Codex model. Config file takes precedence; per-call model arg always wins.
CONCLAVE_GEMINI_MODEL	(unset → CLI default)	Last-resort default Gemini model. Config file takes precedence; per-call model arg always wins.
CONCLAVE_TRUST_DIR	user's home directory (~)	Working directory for spawned CLIs. Codex refuses to start in untrusted dirs; this should point at a directory you've already trusted via codex (run cd ~/<dir> && codex once and accept the trust prompt).

Set them in the MCP server entry. Example (claude mcp add supports -e):

claude mcp add --scope user conclave \
  -e CONCLAVE_TIMEOUT_MS=600000 \
  -- node "/abs/path/to/conclave/src/server.js"

Tools

ask_codex(prompt, model?, tier?)

Forwards a prompt to codex exec - (stdin mode). Returns the CLI's stdout.

model (explicit string) wins if set. Otherwise, if tier is "strong" or "fast", the server resolves it via ~/.conclave.json → built-in fallback. Otherwise falls back to the config default → CONCLAVE_CODEX_MODEL → Codex's own default.

ask_gemini(prompt, model?, tier?)

Forwards a prompt to gemini -p . -o text with the prompt piped on stdin. Returns the CLI's stdout.

Same resolution chain: model → tier (via config or fallback) → config default → CONCLAVE_GEMINI_MODEL → Gemini's own default.

Both tools are stateless — each call is a fresh session. The orchestrator must pass any conversation history in the prompt itself.

Troubleshooting

command not found: codex (or gemini) The npm global bin directory isn't on your PATH. Run npm config get prefix to find it; on Windows that's usually %APPDATA%\npm. Add it to PATH and restart your shell.

claude mcp list shows conclave: ✗ Failed to connect Run the server manually to see the error:

node /abs/path/to/conclave/src/server.js < /dev/null

It should exit cleanly with no output. If it crashes, the stack trace will tell you what's wrong (usually a missing node_modules from skipping npm install, or a Node version below 18).

/conclave doesn't show up in the slash-command picker You forgot to restart Claude Code after copying the command file, or you copied it to the wrong directory. The exact path must be ~/.claude/commands/conclave.md (user scope) — not inside a project's .claude/commands/.

Tool call fails with "Codex/Gemini timed out" Long deliberations can exceed the 5-minute default. Bump CONCLAVE_TIMEOUT_MS (see Configuration).

Codex or Gemini asks to re-authenticate Their session tokens expired. Run codex or gemini once interactively to refresh, then retry the conclave.

Codex errors with "directory is not trusted" / "Not inside a trusted directory" Conclave passes --skip-git-repo-check to Codex by default (since v0.3.1), so this should not normally happen. If you're still seeing it, your Codex version may have stricter trust enforcement. Use the bundled helper to mark a directory as trusted:

npx conclave-trust ~                # trust your home directory
npx conclave-trust C:\              # trust the entire C: drive (Windows)
npx conclave-trust /your/preferred/dir

It writes a [projects.'<dir>'] entry into ~/.codex/config.toml and prints the exact claude mcp add line that sets CONCLAVE_TRUST_DIR for you. Re-register conclave with that command and restart Claude Code.

Gemini errors with Please set an Auth method in your ~/.gemini/settings.json You launched gemini once but quit before picking an auth method, so headless mode has nothing to use. Run gemini interactively again, choose "Login with Google" (or whichever auth applies to your account) on the first prompt, complete the browser flow, and let it land on the chat screen — that step writes ~/.gemini/settings.json. Exit (Ctrl+C or /exit) and retry the conclave.

"Rate limit exceeded" from Codex or Gemini You've hit your subscription's per-window quota. Wait it out or upgrade the plan. Conclave deliberations are 2× more expensive than a normal chat (one call per model per round), so they burn quota faster than you'd expect.

Windows: EINVAL or spawn codex ENOENT Node's spawn on Windows needs the .cmd extension for npm-installed shims. The server already handles this, but if you've installed Codex/Gemini in a non-standard way, override with CONCLAVE_CODEX_CMD / CONCLAVE_GEMINI_CMD pointing at the full path.

Limitations

• Subscription CLIs may apply rate limits. A long deliberation can burn through them quickly.
• The CLIs may emit non-prompt output (status lines, ANSI codes). Most of this is filtered by -o text for Gemini; Codex output is passed through as-is.
• This is a stdio MCP server — it inherits Claude Code's lifecycle. If Claude Code dies, so does the server.
• Each tool call is stateless. Multi-round deliberation works because the orchestrator (Claude) keeps state, not the council members.

License

GNU General Public License v3.0 or later — see LICENSE.

Copyright © 2026 Çağan Öncül.