# Installing deliberation in the OpenAI Codex CLI

[Codex](https://developers.openai.com/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 (`AGENTS.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 `AGENTS.md`).
- `skills/<expert>/SKILL.md` - one skill per expert (`architect`, `plan-reviewer`,
  `scope-analyst`, `code-reviewer`, `security-analyst`, `researcher`, `debugger`),
  each carrying that expert's persona so Codex gets the same guidance natively.

Once installed you get the deliberation MCP tools (`ask-all`, `consensus`,
`ask-gpt` / `ask-gemini` / `ask-grok` / `ask-openrouter`, and the seven experts).

## Provider credentials

The MCP server reads credentials from the host environment. Set only the providers
you use:

| Provider | How it authenticates |
|----------|----------------------|
| GPT (Codex) | OpenAI / Codex CLI auth (Codex login or `OPENAI_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.
