Features and configuration
Everything Deliberation does and every setting that changes it. The home page has the short version.
Commands and tools
In Claude Code you type slash commands. Every other host calls the MCP tool with the same name. All of them advise: the server reads and reasons, and it never edits your files.
| Command | MCP tool | What it does |
|---|---|---|
/deliberation:consensus | consensus-step, consensus | The full loop: blind verdict, panel review, adjudication and revision, round by round, until the panel agrees or the round cap is reached. |
/deliberation:ask-all | ask-all, or panel plus ask-one | One question to every configured reviewer in parallel. The answers come back independently, with no cross-talk. |
/deliberation:ask-gpt/deliberation:ask-gemini/deliberation:ask-grok/deliberation:ask-openrouter | same names | One question to one provider for a single-shot second opinion. |
| Command | What it does |
|---|---|
/deliberation:setup | Configures the provider servers and the orchestration rules. One time. |
/deliberation:help | How to use Deliberation on your host, with example prompts to paste. |
/deliberation:doctor | Health check of config, provider CLIs and keys, sessions and debug flags, and path drift, with fixes. Read-only. |
/deliberation:dashboard | Starts the local read-only dashboard and prints its URL. |
/deliberation:analyze | Reads recent runs and suggests model, reasoning effort and fan-out changes. Advisory. |
/deliberation:codex-login | Logs GPT in on this machine with a ChatGPT device login: a link and a one-time code. |
/deliberation:reload-mcp | Cycles the dashboard process and audits the MCP processes after an update. |
/deliberation:grok-files | Lists, prunes or garbage-collects files uploaded to Grok. |
/deliberation:uninstall | Removes the MCP config, rules and aliases. |
panel returns the exact provider names a fan-out would call, without calling them. Providers that cannot answer right now are listed under unavailable with the reason and are skipped.
Consensus
/deliberation:consensus is the heavy command. The host agent writes the review prompt, votes, and rules on objections, so the engine holds it to three rules.
- Blind verdict first. The host agent records its own verdict before the panel is revealed. The engine does not reveal the panel until it is recorded.
- No self-approval. A round converges only when enough reviewers answered, every reviewer that answered approves, none rejects, no accepted issue is left open, and the host approves. The host's own vote cannot close a round.
- No silent dismissal. Every dismissed or deferred issue carries a written reason in the final report. The engine refuses an adjudication that dismisses an issue without one.
| Key | Default | What it controls |
|---|---|---|
maxRounds | 5 | Rounds before the run ends as unresolved. 1 to 50. |
quorumFloor | 2 | Reviewers that must answer for a round to count. Below it the run ends unresolved with stopReason quorum-lost. |
blindVote | false | Adds a blind pre-vote by the arbiter in the server-side consensus tool, at the cost of one extra call. The host-driven loop always starts with a blind verdict. |
arbiter | "auto" | Who rules on the issues: the host agent, a provider, openrouter:<alias>, or a model record by id. |
maxWallMs | 1800000 (30 min) | Wall-time budget of the server-side loop. It stops before the next round with stopReason budget-exhausted and never aborts a call in flight. |
A reviewer that fails two rounds running is dropped from the panel and reported once under droppedProviders. The confidence label follows how fast the run settled: round 1 is high, rounds 2 and 3 are medium, rounds 4 and 5 are low.
Two entry points share the engine. consensus-step lets the host agent drive the loop as arbiter, one action per call: init, record_blind, dispatch_peers, submit_adjudication, submit_revision. consensus runs the whole loop server-side with a provider as arbiter.
Providers and models
You need at least one provider. Any subset works. Every provider advises; only Gemini can also implement, through the Antigravity CLI in the Claude Code plugin.
| Provider | How it connects | You need |
|---|---|---|
| GPT | Codex CLI on your machine | codex login |
| Gemini | Gemini API (default), or the Antigravity CLI agy (opt-in) | GEMINI_API_KEY |
| Grok | xAI API | XAI_API_KEY |
| OpenRouter models | OpenRouter API. One key gives a built-in panel of three models from three vendors, all through one router | OPENROUTER_API_KEY |
| Local models | Ollama or LM Studio on localhost | no key by default |
OpenRouter built-in panel
With OPENROUTER_API_KEY set and no model records of your own, three built-in records join ask-all and consensus: z-ai/glm-5.3-flashx, openai/gpt-6.1-sol and google/gemini-3.8-flash. All three calls go through one router. Declare your own records under models and they replace the built-in panel.
{
"models": {
"deepseek-v4-pro": {
"provider": "openrouter",
"model": "deepseek/deepseek-v4-pro",
"reasoningEffort": "high",
"askAll": false,
"consensus": false
}
}
}
Local models
Ollama and LM Studio need no key by default. Each has its own block, providers.ollama (default "http://localhost:11434/v1") and providers.lmstudio (default "http://localhost:1234/v1"). Declare a model with provider: "ollama" or provider: "lmstudio".
Gemini: API key or agy
With GEMINI_API_KEY set, every advisory Gemini call goes to the Gemini API, model providers.gemini.apiModel (default "gemini-flash-latest"). Without a key, Gemini falls back to the Antigravity CLI agy. providers.gemini.transport (default "auto") pins the choice: auto, api or agy.
Before choosing agy, read the Antigravity terms, section 6. They list using third-party software to access the service as a breach that may be grounds for suspension. Deliberation drives agy as third-party software. An API key avoids that.
| Key | Default | What it controls |
|---|---|---|
routing.maxFanout | 3 | How many OpenRouter models ask-all calls. |
routing.timeoutPolicy | "longest-peer" | Parallel reviewers share the longest selected limit. "per-provider" keeps each limit. |
providers.defaults.timeout | 600000 in the default config | Per-call ceiling in ms for every provider at once. |
providers.<name>.timeout | unset | Overrides the default for one provider. A model record's own timeout still wins. |
providers.<name>.enabled | true; OpenRouter false until a key is set up | false turns the provider off. Fan-outs skip it and direct calls return errorKind "disabled". Read per call, no restart. |
Experts
8 personas, each a prompt file in prompts/. Call one as a tool, or pass expert to a fan-out tool and every reviewer on the panel takes that role.
| Expert | Tool | Used | Ask it |
|---|---|---|---|
| Scope Analyst | scope-analyst | Before planning | "What am I missing?" "Clarify the scope" |
| Architect | architect | While designing | "How should I structure this?" "What are the tradeoffs?" |
| Plan Reviewer | plan-reviewer | Before work starts | "Review this migration plan" "Is this approach sound?" |
| Researcher | researcher | On unfamiliar ground | "How do I use X?" "Find examples of Y" |
| Code Reviewer | code-reviewer | On a diff | "Review this PR" "What's wrong with this?" |
| Security Analyst | security-analyst | On a diff | "Is this secure?" "Harden this endpoint" |
| Debugger | debugger | When stuck | "Why does this crash?" "Debug this failing test" |
| Writing Editor | writing-editor | Before publishing | "Edit this launch post" "Review the landing page headline and lede" |
Skip the experts for simple file operations, the first attempt at a fix, and questions your agent can answer directly.
Dashboard
An opt-in local page that draws each run as a timeline with one lane per voice. It is read-only and never changes Deliberation state. Nothing is recorded until dashboard.enabled is true.
| View | What it shows |
|---|---|
| Live | The run in progress, one lane per voice on a shared time axis. |
| Runs | Past runs with status, tool, tokens and duration. Open one for its rounds, per-provider latency and event table. |
| Config | Provider health and the effective config after defaults. |
| Stats | Latency and tokens per model, verdict agreement, runs per day. |
| Analyzer | Models that agree more than they add, per-project failures and latency, request size against timeouts. |
| Key | Default | What it controls |
|---|---|---|
enabled | false | Journals runs and allows the dashboard to start. Bound to 127.0.0.1 only. |
capture | "metadata" | "metadata" journals run and verdict metadata only. "content" also journals prompts and responses, secret-scrubbed. |
showPII | false | The page redacts likely personal data in displayed content unless this is on. It does not change what is on disk. |
port | 7717 | Local port. The printed URL carries a per-start token, the only credential. |
maxRuns | 200 | Newest run journals kept. -1 keeps all. |
maxAgeDays | 30 | Days a run journal is kept. -1 keeps all. |
npx -y @antonbabenko/deliberation-mcp dashboard
npx -y @antonbabenko/deliberation-mcp dashboard --stopSessions
Opt-in run history on disk. With sessions.persist on, consensus, the host-driven loop and ask-all return a sessionId.
| Tool | What it does |
|---|---|
session-get | Fetches a recorded run: opinions, verdict, annotations. |
session-revisit | Runs the recorded question again with the current providers and config, and saves a linked child record. |
session-annotate | Appends a note to a run's audit trail. |
| Key | Default | What it controls |
|---|---|---|
persist | false | Writes one record per run. Off means nothing is written to disk. |
captureText | false | Also stores each provider's response body, secret-scrubbed. Off stores the question, verdicts and issue summaries only. |
maxRecords | 200 | Newest records kept. -1 keeps all. |
maxAgeDays | 30 | Days a record is kept. -1 keeps all. |
Analyze and doctor
analyze reads the opt-in debug log and the session store and returns tuning advice. It writes nothing. Timing and agreement are reported side by side and are not joined.
- Timing: per-model p50, p95 and max latency over successful calls, mean tokens, error rate, reasoning effort. Needs
debug.enabled. - Agreement: the verdict agreement rate per model, from the session store.
- Advice: drop a slow or redundant model from
ask-all, lower a model's reasoning effort, changerouting.maxFanout.
doctor is a read-only health check. Each finding has a status (ok, warn, fail, info), a message and, where one exists, a fix. It makes no provider call and starts no login. Run it first when a provider is missing from panel.
The debug log is off by default (debug.enabled). It records one line per provider call and per consensus round, and never prompts, responses or issue descriptions.
Privacy defaults
Deliberation sends nothing to its author. There is no telemetry, analytics, crash reporting or update check. Your prompt, attached files and the orientation bundle go only to the providers you enabled.
| Setting | Default | Meaning |
|---|---|---|
sessions.persist | off | No run history on disk. |
sessions.captureText | off | No response bodies stored, even with history on. |
debug.enabled | off | No latency and token log. |
dashboard.enabled | off | No run journal, no local page. |
dashboard.capture | "metadata" | With the dashboard on, prompts and responses are still not journaled. |
orientation.enabled | on | Up to 6 repo files and 16000 bytes (one of AGENTS.md or CLAUDE.md, manifests, README.md) are added to requests for Grok and OpenRouter, which cannot read your files. Set it to false to stop this. |
Each vendor's own terms apply to what it receives. The codex and agy CLIs run in the current directory and can read files there.
Config file
One JSON file: ~/.config/deliberation/config.json (Windows: %APPDATA%\deliberation\config.json). DELIBERATION_CONFIG overrides the path. Most keys hot-reload; timeouts and model pins are read once at server start.
| Section | Holds |
|---|---|
providers | Connection settings per provider: enabled, key variable, endpoint, model, reasoning effort, timeout. |
models | Named model records for OpenRouter, Ollama and LM Studio, with their fan-out and consensus eligibility. |
routing | Fan-out cap and the timeout policy for parallel calls. |
consensus | Arbiter, round cap, quorum, blind vote, wall-time budget. |
sessions | Run history on disk. |
debug | Latency, token and voting log. |
orientation | The repo files sent to providers that cannot read your files. |
dashboard | The local read-only dashboard. |
The quickest way to a working file is npx -y @antonbabenko/deliberation-mcp init: it finds your keys and CLI logins, writes the config, pings each provider and runs one short demo consensus. It never prints key values.