# Codex Plugin

Install `devboy` as a [Codex plugin](https://developers.openai.com/codex/plugins). Same architecture as the [Claude Code plugin](./claude-code-plugin) — agent-driven bootstrap, no bundled binary, MCP server registration, namespaced skills.

## Install

Codex CLI reads the same `Claude-style marketplace.json` that the Claude Code plugin uses (one of the four marketplace sources documented in [Codex plugin docs](https://developers.openai.com/codex/plugins/build)), so add this repo as a marketplace and install:

```bash
codex plugin marketplace add meteora-pro/devboy-tools
codex plugin install devboy@meteora-devboy
```

OpenAI's official Plugin Directory does not yet accept self-serve community submissions ("coming soon" per the official docs at the time of writing); the per-repo marketplace path above is the supported way to ship today.

## What happens next

The bundled `setup` skill triggers on first use and:

1. Detects plugin context — `$CODEX_PLUGIN_DATA` is set, picks `--agent codex`.
2. Installs `devboy` (npm → fallback to GitHub Release tarball in `${CODEX_PLUGIN_DATA}/bin/`, verified via the per-asset `.sha256` sibling; releases are not code-signed, the SHA file is the integrity check).
3. Runs `devboy onboard --agent codex --yes`.
4. Runs `devboy doctor`.
5. On failure, hands off to `repair`.

After install, restart the Codex session so the MCP server entry binds against the new binary.

## What the plugin ships

| Component | Path inside the plugin |
|---|---|
| Manifest | `plugins/codex/.codex-plugin/plugin.json` |
| Skills (24) | `plugins/codex/skills` symlink → `../claude/skills` |
| MCP server | `plugins/codex/.mcp.json` |
| Binary locator | `plugins/codex/bin/devboy-shim.sh` symlink → `../../claude/bin/devboy-shim.sh` |

Skill names match the source one-to-one (no rename). Namespaced as `/devboy:setup`, `/devboy:review-mr`, …, `/devboy:analyze-usage`.

## Compared to the Claude Code plugin

The two plugins share `/crates/devboy-skills/skills/` as their source of truth and produce identical user-visible skill surface. Differences are mechanical:

| | Claude Code | Codex |
|---|---|---|
| Manifest dir | `.claude-plugin/` | `.codex-plugin/` |
| Plugin data env | `CLAUDE_PLUGIN_DATA` | `CODEX_PLUGIN_DATA` |
| Plugin root env | `CLAUDE_PLUGIN_ROOT` | `CODEX_PLUGIN_ROOT` |
| Subagent format | Markdown | TOML (none today) |
| Marketplace | `meteora-pro/devboy-tools` (this repo, via `.claude-plugin/marketplace.json`) | same `.claude-plugin/marketplace.json` — Codex CLI also reads it (see [Codex plugin sources](https://developers.openai.com/codex/plugins/build)) |

`devboy onboard` dedups against `~/.codex/settings.json#enabledPlugins` the same way it does for Claude.

## Troubleshooting

Same playbook as Claude Code:

- After `setup` finishes, restart the Codex session for the MCP server to bind.
- If `npm install -g` fails, the GitHub Release fallback in `${CODEX_PLUGIN_DATA}/bin/` activates automatically.
- For everything else, run `/devboy:repair`.

## See also

- [ADR-018 — Distribution as Claude Code and Codex plugins](https://github.com/meteora-pro/devboy-tools/blob/main/docs/architecture/adr/ADR-018-plugin-distribution.md)
- [Claude Code plugin install](./claude-code-plugin) — sibling plugin, same architecture
- [Codex Plugin Build Guide](https://developers.openai.com/codex/plugins/build) — upstream plugin spec