plugins/build.md Codex Docs, 2026-03-31 06:35 UTC → 2026-05-01 18:29 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, lifecycle config,

308and assets used to present the plugin across supported surfaces.

254 309 

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

256 311 

264 - SKILL.md Optional: skill instructions319 - SKILL.md Optional: skill instructions

265 - .app.json Optional: app or connector mappings320 - .app.json Optional: app or connector mappings

266 - .mcp.json Optional: MCP server configuration321 - .mcp.json Optional: MCP server configuration

322 - hooks/

323 

324 - hooks.json Optional: lifecycle configuration

267 - assets/ Optional: icons, logos, screenshots325 - assets/ Optional: icons, logos, screenshots

268 326 

269Only `plugin.json` belongs in `.codex-plugin/`. Keep `skills/`, `assets/`,327Only `plugin.json` belongs in `.codex-plugin/`. Keep `skills/`, `assets/`,

270`.mcp.json`, and `.app.json` at the plugin root.328`.mcp.json`, `.app.json`, and lifecycle config files at the plugin root.

271 329 

272Published plugins typically use a richer manifest than the minimal example that330Published plugins typically use a richer manifest than the minimal example that

273appears in quick-start scaffolds. The manifest has three jobs:331appears in quick-start scaffolds. The manifest has three jobs:

296 "skills": "./skills/",354 "skills": "./skills/",

297 "mcpServers": "./.mcp.json",355 "mcpServers": "./.mcp.json",

298 "apps": "./.app.json",356 "apps": "./.app.json",

357 "hooks": "./hooks/hooks.json",

299 "interface": {358 "interface": {

300 "displayName": "My Plugin",359 "displayName": "My Plugin",

301 "shortDescription": "Reusable skills and apps",360 "shortDescription": "Reusable skills and apps",

329- `name`, `version`, and `description` identify the plugin.388- `name`, `version`, and `description` identify the plugin.

330- `author`, `homepage`, `repository`, `license`, and `keywords` provide389- `author`, `homepage`, `repository`, `license`, and `keywords` provide

331 publisher and discovery metadata.390 publisher and discovery metadata.

332- `skills`, `mcpServers`, and `apps` point to bundled components relative to391- `skills`, `mcpServers`, `apps`, and `hooks` point to bundled components

333 the plugin root.392 relative to the plugin root.

334- `interface` controls how install surfaces present the plugin.393- `interface` controls how install surfaces present the plugin.

335 394 

336Use the `interface` object for install-surface metadata:395Use the `interface` object for install-surface metadata:

349- Keep manifest paths relative to the plugin root and start them with `./`.408- Keep manifest paths relative to the plugin root and start them with `./`.

350- Store visual assets such as `composerIcon`, `logo`, and `screenshots` under409- Store visual assets such as `composerIcon`, `logo`, and `screenshots` under

351 `./assets/` when possible.410 `./assets/` when possible.

352- Use `skills` for bundled skill folders, `apps` for `.app.json`, and411- Use `skills` for bundled skill folders, `apps` for `.app.json`,

353 `mcpServers` for `.mcp.json`.412 `mcpServers` for `.mcp.json`, and `hooks` for lifecycle config.

413- If you omit `hooks` and the plugin includes `./hooks/hooks.json`, Codex loads

414 that default lifecycle config automatically.

415 

416### Bundled MCP servers and lifecycle config

417 

418`mcpServers` can point to an `.mcp.json` file that contains either a direct

419server map or a wrapped `mcp_servers` object.

420 

421Direct server map:

422 

423```json

424{

425 "docs": {

426 "command": "docs-mcp",

427 "args": ["--stdio"]

428 }

429}

430```

431 

432Wrapped server map:

433 

434```json

435{

436 "mcp_servers": {

437 "docs": {

438 "command": "docs-mcp",

439 "args": ["--stdio"]

440 }

441 }

442}

443```

444 

445`hooks` can point to one lifecycle JSON file, an array of lifecycle JSON files,

446an inline lifecycle object, or an array of inline lifecycle objects. File paths

447must follow the same `./`-prefixed plugin-root path rules as other manifest

448paths. If you omit the manifest field, Codex still checks `./hooks/hooks.json`.

354 449 

355### Publish official public plugins450### Publish official public plugins

356 451