plugins/build.md Codex Docs, 2026-04-08 00:40 UTC → 2026-05-07 17:08 UTC

10 10 

11For the fastest setup, use the built-in `$plugin-creator` skill.11For the fastest setup, use the built-in `$plugin-creator` skill.

12 12 

13![plugin-creator skill in Codex](/images/codex/plugins/plugin-creator.png)13<CodexScreenshot

14 alt="plugin-creator skill in Codex"

15 lightSrc="/images/codex/plugins/plugin-creator.png"

16 darkSrc="/images/codex/plugins/plugin-creator-dark.png"

17/>

14 18 

15It scaffolds the required `.codex-plugin/plugin.json` manifest and can also19It scaffolds the required `.codex-plugin/plugin.json` manifest and can also

16generate a local marketplace entry for testing. If you already have a plugin20generate a local marketplace entry for testing. If you already have a plugin

17folder, you can still use `$plugin-creator` to wire it into a local21folder, you can still use `$plugin-creator` to wire it into a local

18marketplace.22marketplace.

19 23 

20![how to invoke the plugin-creator skill](/images/codex/plugins/plugin-creator-invoke.png)24<CodexScreenshot

25 alt="how to invoke the plugin-creator skill"

26 lightSrc="/images/codex/plugins/plugin-creator-invoke.png"

27 darkSrc="/images/codex/plugins/plugin-creator-invoke-dark.png"

28/>

21 29 

22### Build your own curated plugin list30### Build your own curated plugin list

23 31 

38single plugin while you are testing, then grow into a larger curated catalog as46single plugin while you are testing, then grow into a larger curated catalog as

39you add more plugins.47you add more plugins.

40 48 

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

50 alt="custom local marketplace in the plugin directory"

51 lightSrc="/images/codex/plugins/codex-local-plugin-light.png"

52 darkSrc="/images/codex/plugins/codex-local-plugin.png"

53/>

54 

55### Add a marketplace from the CLI

56 

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

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

59 

60```bash

61codex plugin marketplace add owner/repo

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

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

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

65```

66 

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

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

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

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

71Git marketplace sources.

72 

73To refresh or remove configured marketplaces:

74 

75```bash

76codex plugin marketplace upgrade

77codex plugin marketplace upgrade marketplace-name

78codex plugin marketplace remove marketplace-name

79```

42 80 

43### Create a plugin manually81### Create a plugin manually

44 82 

93Use a repo marketplace or a personal marketplace, depending on who should be131Use a repo marketplace or a personal marketplace, depending on who should be

94able to access the plugin or curated list.132able to access the plugin or curated list.

95 133 

134<Tabs

135 id="codex-plugins-local-install"

136 param="install-scope"

137 defaultTab="workspace"

138 tabs={[

139 {

140 id: "workspace",

141 label: "Repo",

142 },

143 {

144 id: "global",

145 label: "Personal",

146 },

147 ]}

148>

149 <div slot="workspace">

96 Add a marketplace file at `$REPO_ROOT/.agents/plugins/marketplace.json`150 Add a marketplace file at `$REPO_ROOT/.agents/plugins/marketplace.json`

97 and store your plugins under `$REPO_ROOT/plugins/`.151 and store your plugins under `$REPO_ROOT/plugins/`.

98 152 

131 185 

132 Step 3: Restart Codex and verify that the plugin appears.186 Step 3: Restart Codex and verify that the plugin appears.

133 187 

188 </div>

189 

190 <div slot="global">

134 Add a marketplace file at `~/.agents/plugins/marketplace.json` and store191 Add a marketplace file at `~/.agents/plugins/marketplace.json` and store

135 your plugins under `~/.codex/plugins/`.192 your plugins under `~/.codex/plugins/`.

136 193 

148 205 

149 Step 3: Restart Codex and verify that the plugin appears.206 Step 3: Restart Codex and verify that the plugin appears.

150 207 

208 </div>

209</Tabs>

210 

151The marketplace file points to the plugin location, so those directories are211The marketplace file points to the plugin location, so those directories are

152examples rather than fixed requirements. Codex resolves `source.path` relative212examples rather than fixed requirements. Codex resolves `source.path` relative

153to the marketplace root, not relative to the `.agents/plugins/` folder. See213to the marketplace root, not relative to the `.agents/plugins/` folder. See

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

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

213 keep it inside that root.273 keep it inside that root.

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

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

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

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

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

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

219 first use.281 first use.

220 282 

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

222point somewhere else if your plugin lives outside those example directories. A284`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 in285example directories. A marketplace file can live in the repo where you are

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

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

288 

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

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

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

292 

293```json

294{

295 "name": "remote-helper",

296 "source": {

297 "source": "git-subdir",

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

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

300 "ref": "main"

301 },

302 "policy": {

303 "installation": "AVAILABLE",

304 "authentication": "ON_INSTALL"

305 },

306 "category": "Productivity"

307}

308```

309 

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

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

312whole marketplace.

226 313 

227### How Codex uses marketplaces314### How Codex uses marketplaces

228 315 

233 320 

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

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

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

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

237 325 

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

250 338 

251Every plugin has a manifest at `.codex-plugin/plugin.json`. It can also include339Every 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 or340a `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.341connectors, an `.mcp.json` file that configures MCP servers, lifecycle config,

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

254 343 

255- my-plugin/344<FileTree

256 345 class="mt-4"

257 - .codex-plugin/346 tree={[

258 347 {

259 - plugin.json Required: plugin manifest348 name: "my-plugin/",

260 - skills/349 open: true,

261 350 children: [

262 - my-skill/351 {

263 352 name: ".codex-plugin/",

264 - SKILL.md Optional: skill instructions353 open: true,

265 - .app.json Optional: app or connector mappings354 children: [

266 - .mcp.json Optional: MCP server configuration355 {

267 - assets/ Optional: icons, logos, screenshots356 name: "plugin.json",

357 comment: "Required: plugin manifest",

358 },

359 ],

360 },

361 {

362 name: "skills/",

363 open: true,

364 children: [

365 {

366 name: "my-skill/",

367 open: true,

368 children: [

369 {

370 name: "SKILL.md",

371 comment: "Optional: skill instructions",

372 },

373 ],

374 },

375 ],

376 },

377 {

378 name: ".app.json",

379 comment: "Optional: app or connector mappings",

380 },

381 {

382 name: ".mcp.json",

383 comment: "Optional: MCP server configuration",

384 },

385 {

386 name: "hooks/",

387 open: true,

388 children: [

389 {

390 name: "hooks.json",

391 comment: "Optional: lifecycle configuration",

392 },

393 ],

394 },

395 {

396 name: "assets/",

397 comment: "Optional: icons, logos, screenshots",

398 },

399 ],

400 },

401 ]}

402/>

268 403 

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

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

271 406 

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

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

296 "skills": "./skills/",431 "skills": "./skills/",

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

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

434 "hooks": "./hooks/hooks.json",

299 "interface": {435 "interface": {

300 "displayName": "My Plugin",436 "displayName": "My Plugin",

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

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

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

331 publisher and discovery metadata.467 publisher and discovery metadata.

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

333 the plugin root.469 relative to the plugin root.

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

335 471 

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

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

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

351 `./assets/` when possible.487 `./assets/` when possible.

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

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

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

491 that default lifecycle config automatically.

492 

493### Bundled MCP servers and lifecycle config

494 

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

496server map or a wrapped `mcp_servers` object.

497 

498Direct server map:

499 

500```json

501{

502 "docs": {

503 "command": "docs-mcp",

504 "args": ["--stdio"]

505 }

506}

507```

508 

509Wrapped server map:

510 

511```json

512{

513 "mcp_servers": {

514 "docs": {

515 "command": "docs-mcp",

516 "args": ["--stdio"]

517 }

518 }

519}

520```

521 

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

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

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

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

354 526 

355### Publish official public plugins527### Publish official public plugins

356 528