Plugin developer guide

Publish a Codex plugin from your repository

By HOL · Reviewed by Michael Kantor on

Direct answer

Put the plugin manifest in .codex-plugin/plugin.json and list the plugin in .agents/plugins/marketplace.json at the repository root. Users then run codex plugin marketplace add owner/repo and install it from /plugins. Run hol-guard plugin check before you push, and hol-guard plugin package --runtimes codex to generate the Codex files from a Claude Code plugin. For the public directory, publish to a ChatGPT workspace and submit through the plugin submission portal.

Who this is for

Plugin authors who want Codex users to install their plugin straight from a GitHub repository.

Good fit

  • A Claude Code plugin that should also install in Codex
  • A team that shares internal plugins through a private repository
  • A maintainer preparing a directory submission

Not a fit

  • Plugins whose value is in hooks, commands or subagents, which Codex packages do not carry

Steps

  1. 1.Install HOL Guard

    The Plugin Kit ships inside HOL Guard. It needs Python 3.10 or newer and pipx. If Guard is already installed, upgrade it so the Kit commands below are available.

    pipx install hol-guard
pipx upgrade hol-guard
hol-guard --version

  2. 2.Check the plugin

    The check detects every manifest in the folder, lists skills and MCP servers, and reports what each runtime would reject. It exits 0 when the plugin passes, 1 when it has errors and 2 when it could not run. It reads only the folder, runs no commands and makes no network calls.

    hol-guard plugin check .

  3. 3.Write the Codex package

    Packaging writes .codex-plugin/plugin.json and .mcp.json with your skills and MCP servers, plus hol.provenance.json with a digest of every file. It writes nothing when the check fails.

    hol-guard plugin package . --runtimes codex --out dist/hol-plugin

  4. 4.List the plugin in a marketplace file

    Codex reads .agents/plugins/marketplace.json at the repository root. It needs a name, interface.displayName and a plugins array; each entry needs a name, a source, a policy with installation and authentication, and a category. hol-guard plugin links reports the marketplace step as open until the entry exists.

    hol-guard plugin links .

  5. 5.Install it the way users will

    Add the repository as a marketplace, open the plugin browser, install the plugin and start a new session before using its skills or tools.

    codex plugin marketplace add owner/repo
codex plugin marketplace list

  6. 6.Submit to the plugin directory

    Repository marketplaces work for anyone who can reach the repository. To appear in the directory shared by ChatGPT and Codex, publish the plugin to your ChatGPT workspace, then submit it through the plugin submission portal, where it is reviewed against the submission guidelines.

  7. 7.Add the install block to your README

    hol-guard plugin links --block prints a README block between hol-install-block markers: one hol-guard plugin install command, how to get HOL Guard, and each runtime's own install commands for the runtimes the repository already supports. Paste it into the README; HOL finds it on its next scan and shows the install count on your listing once enough installs are reported.

    hol-guard plugin links . --block

  8. 8.Connect the repository on HOL

    Open the connect page with your repository to verify ownership and claim the listing. hol-guard plugin links prints the same link with the repository filled in.

    hol-guard plugin links .

Limitations

  • The Kit converts manifests and MCP config. It does not submit to the directory or review the plugin for you.
  • Codex packages leave out commands, agents and hooks, and hol-guard plugin check lists each one it drops.
  • A listing, a passing check or a marketplace review is not a safety guarantee. HOL shows its scan evidence on the listing so users can judge for themselves.

Questions

Can I keep the Codex and Claude Code marketplaces in one repository?

Yes. Codex reads .agents/plugins/marketplace.json and Claude Code reads .claude-plugin/marketplace.json, so both can list the same plugin.

Do users need the directory to install my plugin?

No. codex plugin marketplace add owner/repo installs from your repository. The directory adds discovery inside ChatGPT and Codex.

Sources

Related guides

List it on HOL

Connect the repository to verify ownership and claim the listing. New plugins can be submitted for free.

Connect your plugin repository