Best Practice: Plugin Marketplace

Codex CLI v0.121.0 introduced a first-class plugin marketplace — a way to register third-party or internal plugin catalogs and install plugins from them. A marketplace is a git repo (or local directory) containing a marketplace.json manifest that lists plugins and how to fetch them.

← Back to Codex CLI Best Practice

CLI Commands

All marketplace commands live under codex plugin marketplace:

bash

codex plugin marketplace add <SOURCE> [--ref <REF>] [--sparse <PATH>]...
codex plugin marketplace upgrade [MARKETPLACE_NAME]
codex plugin marketplace remove <MARKETPLACE_NAME>

add accepts several source forms:

Source	Example
GitHub shorthand	`codex plugin marketplace add owner/repo`
Git URL	`codex plugin marketplace add https://github.com/owner/repo.git`
SSH URL	`codex plugin marketplace add git@github.com:owner/repo.git`
Local directory	`codex plugin marketplace add /abs/path/to/marketplace`
Relative path	`codex plugin marketplace add ./vendor/internal-market`

Listing is done from the TUI via /plugins (per-marketplace tabs) — there is no codex plugin marketplace list subcommand.

Partial clones

Use --sparse (repeatable) to fetch only the subdirectories you need:

bash

codex plugin marketplace add openai/marketplace-big \
  --sparse plugins/toolkit \
  --sparse skills/release-notes

Codex runs git clone --filter=blob:none --no-checkout and pins the listed paths via git sparse-checkout.

`marketplace.json` Manifest

Codex looks for the manifest at one of:

.agents/plugins/marketplace.json (Codex-native)
.claude-plugin/marketplace.json (Claude Code compatible)

Minimal manifest:

json

{
  "name": "my-marketplace",
  "plugins": [
    { "name": "release-notes", "source": "./plugins/release-notes" }
  ]
}

Full-shape manifest with every supported source variant:

json

{
  "name": "codex-curated",
  "interface": { "displayName": "Codex Curated" },
  "plugins": [
    {
      "name": "local-plugin",
      "source": "./plugins/local-plugin"
    },
    {
      "name": "remote-subdir",
      "source": {
        "source": "git-subdir",
        "url": "openai/joey_marketplace",
        "path": "plugins/toolkit",
        "ref": "main"
      },
      "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_INSTALL",
        "products": ["codex_cli"]
      },
      "category": "dev-tools"
    },
    {
      "name": "remote-url",
      "source": {
        "source": "url",
        "url": "https://github.com/owner/repo.git",
        "ref": "main"
      }
    }
  ]
}

Field Reference

Field	Required	Notes
`name`	yes	Marketplace key — also the directory name under `$CODEX_HOME`
`interface.displayName`	no	Label shown in `/plugins`
`plugins[].name`	yes	Plugin key
`plugins[].source`	yes	Bare string (local path) or object discriminated by `"source"`
`plugins[].policy.installation`	no	`NOT_AVAILABLE \| AVAILABLE \| INSTALLED_BY_DEFAULT` (default `AVAILABLE`)
`plugins[].policy.authentication`	no	`ON_INSTALL \| ON_USE`
`plugins[].policy.products`	no	e.g. `["codex_cli"]`
`plugins[].category`	no	Taxonomy string for the UI

source object types:

"local" — { "source": "local", "path": "./..." }
"url" — { "source": "url", "url": "...", "path"?, "ref"?, "sha"? }
"git-subdir" — { "source": "git-subdir", "url": "...", "path": "...", "ref"?, "sha"? } (path required)

On-Disk Layout

Codex caches marketplace contents and installed plugins under $CODEX_HOME (usually ~/.codex/):

$CODEX_HOME/
├── config.toml                   # [marketplaces.<name>] entries
├── .tmp/marketplaces/
│   └── <marketplace_name>/       # cloned manifest root
└── plugins/cache/
    └── <marketplace_name>/
        └── <plugin_name>/
            └── <version>/        # "local" when unversioned
                └── .codex-plugin/plugin.json

`config.toml` Bookkeeping

codex plugin marketplace add records the marketplace in config.toml — you rarely edit these by hand, but they look like this:

toml

[marketplaces.my-marketplace]
source_type   = "git"
source        = "https://github.com/owner/repo.git"
ref           = "main"
sparse_paths  = ["plugins/toolkit"]
last_updated  = "2026-04-18T00:00:00Z"
last_revision = "abc123..."

upgrade re-runs git ls-remote against each entry and re-clones only if the SHA has moved.

Running Plugin Workflows

After installation, plugin contents (skills, agents, MCP servers, commands) are discoverable through the usual Codex surfaces:

/plugins — browse + install/uninstall per marketplace tab
/skills + $skill-name — for plugin-provided skills
/agent — for plugin-provided subagents
[mcp_servers.*] — auto-wired if the plugin declares them

Anti-Patterns

Anti-Pattern	Fix
Using `codex marketplace add ...` (top-level)	The command is `codex plugin marketplace add`
Hand-editing `[marketplaces.*]` in config.toml	Use `add` / `upgrade` / `remove` — Codex manages the keys
Publishing marketplaces without `marketplace.json` at one of the two known paths	Use `.agents/plugins/marketplace.json` or `.claude-plugin/marketplace.json`
Relying on `source: "./outside"` paths that escape the marketplace root	Local sources must stay under the marketplace directory
Cloning giant marketplace repos fully	Use `--sparse <PATH>` to fetch only what you need

Best Practice: Plugin Marketplace ​

CLI Commands ​

Partial clones ​

marketplace.json Manifest ​

Field Reference ​

On-Disk Layout ​

config.toml Bookkeeping ​

Running Plugin Workflows ​

Anti-Patterns ​