Installing Deliberation in the OpenAI Codex CLI
Codex (external) installs reusable bundles as native
plugins. The Deliberation plugin lives in plugins/deliberation/ in this repo
and is discoverable through a repo-scoped marketplace, all generated by
scripts/sync-hosts.js from the canonical sources (docs/tool-guide.md, prompts/*.md).
Install
The install steps for Codex CLI are on the install page, with every other host. This page has the rest: what the plugin ships, provider keys, updating and notes.
What the plugin ships
Plugin root: plugins/deliberation/
.codex-plugin/plugin.json- manifest.interfacecarries the requireddisplayName,developerName,category, andcapabilitiesfields;versionis kept in sync withversion.jsonby the release pipeline..mcp.json- registers the MCP server (npx -y @antonbabenko/deliberation-mcp, stdio).skills/deliberation/SKILL.md- "when to delegate" (fromdocs/tool-guide.md).skills/<expert>/SKILL.md- one skill per expert (architect,plan-reviewer,scope-analyst,code-reviewer,security-analyst,researcher,debugger,writing-editor), each carrying that expert's persona so Codex gets the same guidance natively.skills/reload-mcp/SKILL.md- steps to pick up a new version (clear the npx cache, stop the dashboard, restart the MCP server).
Once installed you get the Deliberation MCP tools (ask-all, consensus,
ask-gpt / ask-gemini / ask-grok / ask-openrouter, and the eight experts).
Provider credentials
The MCP server reads credentials from the host environment. Set only the providers you use:
| Provider | How it authenticates |
|---|---|
| GPT (Codex) | Codex CLI auth (codex login, e.g. ChatGPT - codex login --device-auth on a remote machine; or CODEX_ACCESS_TOKEN; else CODEX_API_KEY) |
| Gemini | GEMINI_API_KEY (Google AI Studio key). Opt-in fallback: the Antigravity CLI (agy) - see the terms note below |
| Grok (xAI) | XAI_API_KEY |
| OpenRouter | OPENROUTER_API_KEY (advisory-only; declare models in ~/.config/deliberation/config.json) |
Gemini note: with no key, Gemini falls back to the Antigravity CLI (agy). Read the
Antigravity terms (external) first. Section 6 lists "Using third
party software, tools, or services to access the Service (e.g. using OpenClaw with
Antigravity OAuth)" as a breach that "may be grounds for suspension or termination of your
Antigravity and/or Gemini CLI accounts". Deliberation drives agy as third-party software.
Missing keys just disable that one provider.
Notes / verified vs unverified
Verified against developers.openai.com/codex/plugins (+ the openai/codex plugin
spec): the .codex-plugin/plugin.json manifest shape and required interface
fields; .mcp.json and skills/<name>/SKILL.md at the plugin root; the
repo-scoped .agents/plugins/marketplace.json and codex plugin marketplace add owner/repo install flow; the root-source.path-rejected requirement
(openai/codex#17066).
[unverified] The submission path for the curated "Codex Plugin Marketplace" (the
@plugin-creator skill scaffolds entries; the public curation/submission flow is
not yet pinned). Confirm at developers.openai.com/codex/plugins before claiming a
curated-directory listing.
Updating
The plugin starts the server with npx -y @antonbabenko/deliberation-mcp. The npm package
does not include this repository's scripts/ folder. After an update:
# stop the dashboard; prints "no running dashboard" if none runs
npx -y @antonbabenko/deliberation-mcp dashboard --stop
# drop the cached old build of this package (macOS, Linux)
find ~/.npm/_npx -type d -path '*/@antonbabenko/deliberation-mcp' -prune -exec rm -rf {} +On Windows, dashboard --stop is not supported: close the dashboard process first, then
delete the @antonbabenko\deliberation-mcp folders under %LocalAppData%\npm-cache\_npx.
Then start a new Codex session so it starts the new server. The reload-mcp skill gives the
same steps. In a clone of this repository, bash scripts/commands/reload-mcp.sh clears the cached package, restarts the dashboard
and audits the running Deliberation processes.
If you use the dashboard, start it again on the new version with
npx -y @antonbabenko/deliberation-mcp dashboard.