How to add a local Codex plugin marketplace

A local Codex plugin marketplace lets a repo or personal workspace expose plugin bundles without publishing them through a public directory. It is the handoff between a finished plugin folder and the Codex plugin browser, so the important check is whether Codex can resolve the marketplace name and see the plugins inside it.

Codex reads a local marketplace from a supported manifest path under the marketplace root. For a repo-scoped marketplace, keep the manifest at .agents/plugins/marketplace.json and point each plugin entry's source.path at the plugin directory relative to that root.

Use codex plugin marketplace add when the marketplace root is outside Codex's default repo or personal locations, or when you want Codex to track that source explicitly. The command writes a marketplace entry to Codex configuration, while codex plugin marketplace list and codex plugin list prove that the source is registered and the plugin catalog can be read.

1. Create the supported manifest directory in the marketplace root.

   $ mkdir -p .agents/plugins

   Use the project root for a repo marketplace, or a dedicated personal directory such as ~/dev/local-codex-marketplace for a personal curated list.

2. Add the marketplace manifest.

   $ vi .agents/plugins/marketplace.json

   .agents/plugins/marketplace.json

   {
     "name": "local-review-tools",
     "plugins": [
       {
         "name": "review-helper",
         "source": {
           "source": "local",
           "path": "./plugins/review-helper"
         },
         "policy": {
           "installation": "AVAILABLE",
           "authentication": "ON_INSTALL"
         },
         "category": "Productivity"
       }
     ]
   }

   source.path is resolved relative to the marketplace root, not relative to .agents/plugins. The JSON check only proves the manifest parses; the Codex commands below still prove marketplace discovery.
   Tool: JSON Validator

3. Add the marketplace root to Codex.

   $ codex plugin marketplace add . --json
   {
     "marketplaceName": "local-review-tools",
     "installedRoot": "/Users/alex/dev/local-codex-marketplace",
     "alreadyAdded": false
   }

   Run the command from the marketplace root, or replace ./ with the absolute path to that root.

4. List the configured marketplace sources.

   $ codex plugin marketplace list
   MARKETPLACE         ROOT
   local-review-tools  /Users/alex/dev/local-codex-marketplace

5. Confirm Codex can read plugins from the new marketplace.

   $ codex plugin list --marketplace local-review-tools --available --json
   {
     "installed": [],
     "available": [
       {
         "pluginId": "review-helper@local-review-tools",
         "name": "review-helper",
         "marketplaceName": "local-review-tools",
         "version": "1.0.0",
         "installed": false,
         "enabled": false,
         "installPolicy": "AVAILABLE",
         "authPolicy": "ON_INSTALL"
       }
     ]
   }

   The --available flag requires --json. Without it, codex plugin list shows installed plugins only.