Clarify personal plugin directories

What is the type of issue?

Documentation is confusing

What is the issue?

The OpenAI Developers docs on local plugins (aka "personal" plugins) say,

Add a marketplace file at ~/.agents/plugins/marketplace.json and store your plugins under ~/.codex/plugins/. Personal marketplace example Step 1: Copy the plugin folder into ~/.codex/plugins/my-plugin. ``sh mkdir -p ~/.codex/plugins cp -R /absolute/path/to/my-plugin ~/.codex/plugins/my-plugin ` Step 2: Add or update ~/.agents/plugins/marketplace.json so that the plugin entry’s source.path points to that directory. Step 3: Restart Codex and verify that the plugin appears. The marketplace file points to the plugin location, so those directories are examples rather than fixed requirements. Codex resolves source.path relative to the marketplace root, not relative to the .agents/plugins/` folder. See Marketplace metadata for the file format.

And then under marketplace metadata:

- Keep source.path relative to the marketplace root, start it with ./, and keep it inside that root.

If the marketplace root is ~/.agents/plugins/, and the plugin folder is ~/.codex/plugins, how is the source.path supposed to be "inside that root"? It would have to be ../.codex/plugins.

I asked Codex about this (GPT-5.4, xhigh), and it said,

The only reading that makes the current docs coherent is that the personal marketplace root is ~, not ~/.agents/plugins/. The docs say source.path is resolved relative to the "marketplace root", explicitly "not relative to the .agents/plugins/ folder", and that it must start with ./ and stay inside that root. Read together, that implies a personal plugin path like ./.codex/plugins/my-plugin, not ../.codex/plugins/my-plugin. So yes: if you assume the root is ~/.agents/plugins/, the page is self-contradictory. The likely issue is that "marketplace root" is underspecified in the docs. In practice, treat it as the enclosing home directory for personal marketplaces, and as the repo root for repo-scoped marketplaces.

Would you please clarify the docs on this?

Where did you find it?

https://developers.openai.com/codex/plugins/build?install-scope=global