plugins/build.md Codex Docs, 2026-04-14 18:31 UTC → 2026-04-25 00:42 UTC

40 40 

41![custom local marketplace in the plugin directory](/images/codex/plugins/codex-local-plugin-light.png)41![custom local marketplace in the plugin directory](/images/codex/plugins/codex-local-plugin-light.png)

42 42 

43### Add a marketplace from the CLI

44 

45Use `codex plugin marketplace add` when you want Codex to install and track a

46marketplace source for you instead of editing `config.toml` by hand.

47 

48```bash

49codex plugin marketplace add owner/repo

50codex plugin marketplace add owner/repo --ref main

51codex plugin marketplace add https://github.com/example/plugins.git --sparse .agents/plugins

52codex plugin marketplace add ./local-marketplace-root

53```

54 

55Marketplace sources can be GitHub shorthand (`owner/repo` or

56`owner/repo@ref`), HTTP or HTTPS Git URLs, SSH Git URLs, or local marketplace root

57directories. Use `--ref` to pin a Git ref, and repeat `--sparse PATH` to use a

58sparse checkout for Git-backed marketplace repos. `--sparse` is valid only for

59Git marketplace sources.

60 

61To refresh or remove configured marketplaces:

62 

63```bash

64codex plugin marketplace upgrade

65codex plugin marketplace upgrade marketplace-name

66codex plugin marketplace remove marketplace-name

67```

68 

43### Create a plugin manually69### Create a plugin manually

44 70 

45Start with a minimal plugin that packages one skill.71Start with a minimal plugin that packages one skill.

211 personal installs, a common pattern is `./.codex/plugins/<plugin-name>`.237 personal installs, a common pattern is `./.codex/plugins/<plugin-name>`.

212- Keep `source.path` relative to the marketplace root, start it with `./`, and238- Keep `source.path` relative to the marketplace root, start it with `./`, and

213 keep it inside that root.239 keep it inside that root.

240- For local entries, `source` can also be a plain string path such as

241 `"./plugins/my-plugin"`.

214- Always include `policy.installation`, `policy.authentication`, and242- Always include `policy.installation`, `policy.authentication`, and

215 `category` on each plugin entry.243 `category` on each plugin entry.

216- Use `policy.installation` values such as `AVAILABLE`,244- Use `policy.installation` values such as `AVAILABLE`,

218- Use `policy.authentication` to decide whether auth happens on install or246- Use `policy.authentication` to decide whether auth happens on install or

219 first use.247 first use.

220 248 

221The marketplace controls where Codex loads the plugin from. `source.path` can249The marketplace controls where Codex loads the plugin from. A local

222point somewhere else if your plugin lives outside those example directories. A250`source.path` can point somewhere else if your plugin lives outside those

223marketplace file can live in the repo where you are developing the plugin or in251example directories. A marketplace file can live in the repo where you are

224a separate marketplace repo, and one marketplace file can point to one plugin252developing the plugin or in a separate marketplace repo, and one marketplace

225or many.253file can point to one plugin or many.

254 

255Marketplace entries can also point at Git-backed plugin sources. Use

256`"source": "url"` when the plugin lives at the repository root, or

257`"source": "git-subdir"` when the plugin lives in a subdirectory:

258 

259```json

260{

261 "name": "remote-helper",

262 "source": {

263 "source": "git-subdir",

264 "url": "https://github.com/example/codex-plugins.git",

265 "path": "./plugins/remote-helper",

266 "ref": "main"

267 },

268 "policy": {

269 "installation": "AVAILABLE",

270 "authentication": "ON_INSTALL"

271 },

272 "category": "Productivity"

273}

274```

275 

276Git-backed entries may use `ref` or `sha` selectors. If Codex can't resolve a

277marketplace entry's source, it skips that plugin entry instead of failing the

278whole marketplace.

226 279 

227### How Codex uses marketplaces280### How Codex uses marketplaces

228 281 

233 286 

234- the curated marketplace that powers the official Plugin Directory287- the curated marketplace that powers the official Plugin Directory

235- a repo marketplace at `$REPO_ROOT/.agents/plugins/marketplace.json`288- a repo marketplace at `$REPO_ROOT/.agents/plugins/marketplace.json`

289- a Claude-style marketplace at `$REPO_ROOT/.claude-plugin/marketplace.json`

236- a personal marketplace at `~/.agents/plugins/marketplace.json`290- a personal marketplace at `~/.agents/plugins/marketplace.json`

237 291 

238You can install any plugin exposed through a marketplace. Codex installs292You can install any plugin exposed through a marketplace. Codex installs

250 304 

251Every plugin has a manifest at `.codex-plugin/plugin.json`. It can also include305Every plugin has a manifest at `.codex-plugin/plugin.json`. It can also include

252a `skills/` directory, an `.app.json` file that points at one or more apps or306a `skills/` directory, an `.app.json` file that points at one or more apps or

253connectors, and assets used to present the plugin across supported surfaces.307connectors, an `.mcp.json` file that configures MCP servers, and assets used to

308present the plugin across supported surfaces.

254 309 

255- my-plugin/310- my-plugin/

256 311