claude-council

A Claude Code plugin that asks AI coding agents the same question in parallel. Compare their answers when one model's bias could mislead you: architecture decisions, debugging dead ends, security reviews, or framework choices.

Install

You need curl and jq on macOS, Linux, or Windows through Git Bash.

/plugin marketplace add hex/claude-marketplace
/plugin install claude-council

Give it at least one provider in the shell you start Claude Code from:

export OPENAI_API_KEY="..."
# Or GEMINI_API_KEY, XAI_API_KEY, PERPLEXITY_API_KEY,
# KIMI_API_KEY, OPENROUTER_API_KEY

The codex, agy (Antigravity), grok, kimi, and cursor-agent CLIs use your existing subscriptions without an API key. Claude Code itself, the Copilot CLI and OpenCode can sit too, when named in --providers. A local ollama model needs no key or external network. With none of these, --local uses Claude subagents. See provider selection and local councils.

First run in 60 seconds

Read what gets sent and saved before asking about your code.

/claude-council:status
/claude-council:ask "Should I use UUID or BIGINT primary keys for a SaaS users table?"

Each provider answers independently. Claude writes a synthesis of their agreement, disagreements, and recommendation. Agreement is not verification: the models share your description and its assumptions. The synthesis names the premise that could change the answer.

Features

The reference lists every flag, variable, model default, and limit. Architecture covers the implementation. TESTING.md covers tests, releases, and adding a provider.

Heads-up side-check

Opt in through the "Heads-up side-check" row in /config or the project's .claude/council-heads-up.json. One seat, codex by default, checks recent turns and tool results while Claude works. For a Write or an Edit, it gets the text Claude wrote. The note shows what went where. Learn more expands it; Tell Claude puts a draft in the prompt without sending it. Read the data limits and off switch and the heads-up guide.

The pane

With CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1, the pane opens inside Claude Code, as in the animation above. Each seat has one row with its model, a bar for its state, its time, and a button for what it does now: cancel, retry, open, or fold. When the run ends, the synthesis opens at the top with the answers folded below it. Reopen the last run with /council-pane. Inside tmux, the mod asks once which pane you want.

Mods are early access. The mod guide lists keys, settings, and limits. It also lets Claude call the council as a tool; every call asks you first.

What the mod runs, reads and sends

The mod makes no network calls of its own. It starts the programs below from an argument array, never a shell string, and never hands bash -c a script. Your text reaches model providers only through the first two:

• bash scripts/run-council.sh when Claude calls the council tool and you choose Send to the council. It sends your question to the providers you set up.
• bash scripts/heads-up.sh, only with the heads-up side-check on. It reads this session's transcript (by default the last 5 turns and up to 8 tool results of 2,000 characters each) and sends that digest to one seat, codex unless you pick another. The run directory keeps digest.md and prompt.md, exactly what left the machine, until the mod reads the result and removes it. The codex seat runs in that directory under a codex home of its own: your model and effort, a link to your auth.json so a token refresh reaches your login (without one, your CODEX_API_KEY or OPENAI_API_KEY signs codex in), and none of your plugins, hooks, AGENTS.md, skills or MCP servers.
• bash scripts/seat-info.sh discover, model <seat> or allowlisted <seat> during /heads-up setup and /heads-up on <seat>. It checks which seats this machine can run and sends nothing.
• codex debug models during /heads-up setup with the codex seat, to list its models. That command belongs to codex, and so does any request it makes.
• kill -0 <pid> to check a council run is still alive. It sends no signal.
• rm -rf and mv -f on its own run directories under $TMPDIR/council-mod.<session id>, to clean up a finished run and to answer the retry offer.

It writes files in that $TMPDIR directory, including model.json and avoid.txt, which heads-up.sh reads. Outside it, it writes one file, .claude/council-heads-up.json in the project, and only from /heads-up setup, /heads-up on, /heads-up off or a note's Turn off. That file is the heads-up switch. Claude Code itself does not read it.

It touches the prompt in two places. With wake_on_async_done on, it submits The background council job <id> has finished. Fetch it with /claude-council:result <id> and summarise it. once a background job finishes. A note's Tell Claude puts a draft in the prompt box, and you decide whether to send it.

It reads the text of each Bash command Claude runs, only to spot a call to run-council.sh. Just before that call it sets COUNCIL_MOD_PANE_DIR, so the run draws in this pane, and clears it when tmux owns the pane. It reads TMPDIR and TMUX. It turns on the claude-council.heads_up setting only when you pick "every project" in /heads-up setup.

Without the mod, tmux opens a side pane that streams answers and each provider's status. It offers to retry failed seats. Esc closes it. --no-pane or COUNCIL_NO_PANE=1 turns it off. Outside both pane modes, answers arrive in the chat. See terminal integration.

The council and tmux animations show real answers to "Should a single-node demo app use SQLite or Postgres?" Codex and Antigravity use subscriptions; Gemini and OpenAI use their APIs. Kimi is a rate-limit fixture. The heads-up animation uses a fake seat and a real Claude Code host. Capture scripts and raw frames record how to reproduce them.

What a CLI seat loads

Every CLI seat runs from an empty directory, $TMPDIR/claude-council-<uid>/seat, where <uid> is your numeric user id. The CLAUDE.md, AGENTS.md, rules, skills, hooks and MCP servers of the project you ask from don't reach it. The directory doesn't limit what a seat can read: codex, for example, can still open any file by its full path.

The directory is read-only. That stops a seat writing a file there, but not a seat that changes the mode first. A seat also refuses to start when it finds anything in it, and names the path so you can look before you remove it. A file that lands while other seats are running can reach them; the next seat to start refuses.

The seats below also run under a home of their own, in $TMPDIR/claude-council-<uid>/seat-home. It links only to what the CLI needs to sign in and start. Only you can open either directory, and a seat refuses to start when one of them belongs to another user or is a symlink.