How to Publish Your Developed Plugin to the Codex Marketplace

To publish your plugin to the Codex Marketplace, create a directory under plugins/, add a valid .codex-plugin/plugin.json manifest, register the entry in .agents/plugins/marketplace.json, and merge your changes into the main branch of the openai/plugins repository.

The openai/plugins repository hosts the official Codex Marketplace, which functions as a conventional Git-based index that Codex-enabled tools scan to discover available extensions. When you publish your developed plugin by submitting a manifest and registering it in the marketplace index, it becomes immediately discoverable by all Codex CLI users.

Create the Plugin Directory

Begin by creating a new folder under the plugins/ directory in the repository root. The marketplace scanner monitors this directory to identify available plugins.

For example, if your plugin is named "my-awesome-plugin", create:

plugins/my-awesome-plugin/

Add the Required Plugin Manifest

Inside your plugin directory, create the file plugins/my-awesome-plugin/.codex-plugin/plugin.json. This manifest tells Codex how to load the plugin and what commands or skills it provides.

The file must contain required fields including name, description, version, author, and entryPoints. Here is a minimal valid example:

{
  "name": "my-awesome-plugin",
  "shortDescription": "A demo plugin for Codex",
  "description": "Provides a simple command that echoes back the user's input.",
  "version": "0.1.0",
  "author": "Your Name <[email protected]>",
  "entryPoints": {
    "commands": [
      {
        "name": "echo",
        "description": "Echo back the supplied text",
        "script": "scripts/echo.js"
      }
    ]
  }
}

See a real-world implementation in the Zoom plugin at plugins/zoom/.codex-plugin/plugin.json.

Register in the Marketplace Index

To make your plugin discoverable, add an entry to the central marketplace index file .agents/plugins/marketplace.json. This file serves as the canonical list of all publicly available plugins.

Add a JSON object pointing to your plugin directory:

[
  {
    "name": "my-awesome-plugin",
    "path": "plugins/my-awesome-plugin"
  }
]

Validate with Repository CI

Verify your manifest conforms to repository standards before submitting by running the linting suite:

npm test

The repository also runs a CI workflow defined in .github/workflows/ci.yml on each pull request. This prevents malformed plugins from breaking the marketplace index.

Submit and Merge Your Changes

Commit your changes to the main branch or open a pull request. Once the PR is merged, the CI pipeline automatically publishes the updated marketplace. Because the marketplace is a live-updating Git repository, merging makes your plugin immediately available to all Codex-enabled environments.

Test Your Plugin Locally

Optionally verify functionality before publishing using the Codex CLI:

# From the repository root

codex-cli plugin install plugins/my-awesome-plugin

# Verify the plugin appears in the list

codex-cli plugin list

This confirms the plugin loads correctly before you submit it to the public index.

Optional: API-Key Marketplace Registration

If you want your plugin discoverable only when users authenticate with an API key, also add an entry to .agents/plugins/api_marketplace.json. This separate index handles authenticated-only plugins while .agents/plugins/marketplace.json remains for public access.

Summary

• Create a directory under plugins/ for your plugin files.
• Add a manifest at .codex-plugin/plugin.json with required metadata including name, version, author, and entryPoints.
• Register publicly by adding an entry to .agents/plugins/marketplace.json.
• Validate your changes with npm test or the CI workflow in .github/workflows/ci.yml.
• Merge to main to make the plugin live in the Codex Marketplace.
• Test locally using codex-cli plugin install before submitting.

Frequently Asked Questions

What fields are required in the plugin.json manifest?

The plugin.json manifest must include name, description, version, author, and entryPoints. The entryPoints object defines the plugin's capabilities, such as commands. Refer to the example in plugins/zoom/.codex-plugin/plugin.json for a complete implementation.

How long does it take for my plugin to appear in the marketplace after merging?

Your plugin becomes available immediately after your pull request is merged into the main branch. The Codex Marketplace is a Git-based index that updates automatically when the CI pipeline processes the merged changes.

Can I publish private plugins that require API key authentication?

Yes. In addition to registering in .agents/plugins/marketplace.json, add an entry to .agents/plugins/api_marketplace.json. This secondary index is specifically for plugins that should only appear when users authenticate with an API key.

How do I update an existing plugin in the marketplace?

Modify the plugin files in your existing plugins/<plugin-name>/ directory and update the version field in .codex-plugin/plugin.json. After merging these changes to main, the marketplace updates automatically. You do not need to modify the marketplace index files unless you change the plugin path or name.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}