Deliberationv4.6.1

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. interface carries the required displayName, developerName, category, and capabilities fields; version is kept in sync with version.json by the release pipeline.
  • .mcp.json - registers the MCP server (npx -y @antonbabenko/deliberation-mcp, stdio).
  • skills/deliberation/SKILL.md - "when to delegate" (from docs/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:

bash
# 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.

Rendered from docs/hosts/codex.md in the repository.

Type to search the site.