Skip to content

codex.md

Latest commit

 

History

History
75 lines (55 loc) · 3.42 KB

codex.md

File metadata and controls

75 lines (55 loc) · 3.42 KB
Raw

Installing deliberation in the OpenAI Codex CLI

Codex 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

codex plugin marketplace add antonbabenko/deliberation

Then open the plugin directory with /plugins inside Codex and install deliberation. Codex reads the repo-scoped marketplace at .agents/plugins/marketplace.json, whose entry points at the plugin subdirectory ./plugins/deliberation (a root source.path of . is rejected - openai/codex#17066 - so the plugin is shipped in a subdirectory).

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 - process audit and graceful dashboard recycling after deliberation updates.

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 The Antigravity CLI (agy) - sign in once with the CLI
Grok (xAI) XAI_API_KEY
OpenRouter OPENROUTER_API_KEY (advisory-only; declare models in ~/.config/deliberation/config.json)

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

When deliberation is updated, invoke the reload-mcp skill or run:

bash scripts/commands/reload-mcp.sh

This audits active deliberation processes, protects running workloads, cleans up orphaned processes, and safely cycles the background dashboard daemon if running. Next tool calls and new sessions will automatically resolve the updated server code.