This repository includes a portable Agent Plugin package for OpenAI Codex. The package exposes the same MCP server and shared skills used by the Claude Code plugin.
The portable package is defined by two files at the repository root:
plugin.json: the portable plugin manifest.mcp.json: the Codex MCP configuration. It starts the server on demand withuv, uses${PLUGIN_ROOT}for the installed plugin directory, stores the virtual environment below${PLUGIN_DATA}, and uses the shared user config location unlessGERRIT_CONFIG_PATHis explicitly set.
The Codex-specific .codex-plugin/plugin.json overlays env_vars for the
portable MCP server, forwarding GERRIT_CONFIG_PATH and XDG_CONFIG_HOME from
the Codex process. This preserves explicit overrides and custom XDG config
directories without setting defaults for either variable. The portable
mcp.json remains the source of the server command, arguments, and virtual
environment; it does not support Codex's env_vars field directly.
The shared skills/ directory is discovered automatically by the portable
plugin manifest. The Claude-specific .claude-plugin/plugin.json and
.mcp.json remain in place for Claude Code and are intentionally separate from
the portable files.
Codex can use a local or Git-backed marketplace. For a local checkout, add the repository or a marketplace containing the repository plugin:
codex plugin marketplace add <path-to-gerrit-mcp-server>
codex plugin list --available --json
codex plugin add gerrit@gerrit-mcp --jsonOpen a new Codex session after installation. Use /plugins to inspect installed
plugins and verify that the Gerrit tools are available.
The setup skill is explicit-only. Invoke it as $gerrit:setup in Codex. It
creates or repairs the shared user config file, outside the
plugin installation and data directories. Claude Code and Codex use
platformdirs.user_config_path("gerrit-mcp") / "gerrit_config.json" by default;
a nonempty GERRIT_CONFIG_PATH overrides it. The manifest does not set that
override. Move an existing plugin-data config to the shared location or select
it explicitly with GERRIT_CONFIG_PATH; no credentials are copied
automatically. The setup skill supports the same authentication methods as the
Claude Code setup flow.
The root plugin.json declares hooks/hooks.json through
extensions.com.openai.hooks, so supported Codex versions can run the
SessionStart configuration hook. Review and trust the plugin hook in /hooks
after installation. Codex CLI 0.155.1 ignored plugin-bundled SessionStart
hooks even with this declaration (openai/codex#39895); upgrade Codex rather than
removing plugin.json. Removing it leaves ${CLAUDE_PLUGIN_ROOT} unexpanded in
.mcp.json, and the MCP server cannot start. Run $gerrit:setup to create or
repair the configuration; MCP startup success or failure is the authoritative
validation.
The hook accepts PLUGIN_ROOT and PLUGIN_DATA as well as the
Claude-compatible names. Plugin hooks must be reviewed and trusted before Codex
runs them.
Run the package and hook tests without launching Codex:
uv run pytest tests/integration/test_plugin_package.pyFor the manual Codex client smoke test and the full test commands, see the Testing Guide.