plugins/build.md Codex Docs, 2026-04-25 06:37 UTC → 2026-05-18 22:01 UTC

4plugins in Codex, see [Plugins](https://developers.openai.com/codex/plugins). If you are still iterating on4plugins in Codex, see [Plugins](https://developers.openai.com/codex/plugins). If you are still iterating on

5one repo or one personal workflow, start with a local skill. Build a plugin5one repo or one personal workflow, start with a local skill. Build a plugin

6when you want to share that workflow across teams, bundle app integrations or6when you want to share that workflow across teams, bundle app integrations or

7MCP config, or publish a stable package.7MCP config, package lifecycle hooks, or publish a stable package.

8 8 

9## Create a plugin with `$plugin-creator`9## Create a plugin with `$plugin-creator`

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/>

42 54 

43### Add a marketplace from the CLI55### Add a marketplace from the CLI

44 56 

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

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

121 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">

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

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

124 152 

157 185 

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

159 187 

188 </div>

189 

190 <div slot="global">

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

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

162 193 

174 205 

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

176 207 

208 </div>

209</Tabs>

210 

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

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

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

286 320 

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

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

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

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

291 325 

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

303### Plugin structure337### Plugin structure

304 338 

305Every 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

306a `skills/` directory, an `.app.json` file that points at one or more apps or340a `skills/` directory, a `hooks/` directory for lifecycle hooks, an `.app.json`

307connectors, an `.mcp.json` file that configures MCP servers, and assets used to341file that points at one or more apps or connectors, an `.mcp.json` file that

308present the plugin across supported surfaces.342configures MCP servers, and assets used to present the plugin across supported

309 343surfaces.

310- my-plugin/344 

311 345<FileTree

312 - .codex-plugin/346 class="mt-4"

313 347 tree={[

314 - plugin.json Required: plugin manifest348 {

315 - skills/349 name: "my-plugin/",

316 350 open: true,

317 - my-skill/351 children: [

318 352 {

319 - SKILL.md Optional: skill instructions353 name: ".codex-plugin/",

320 - .app.json Optional: app or connector mappings354 open: true,

321 - .mcp.json Optional: MCP server configuration355 children: [

322 - assets/ Optional: icons, logos, screenshots356 {

357 name: "plugin.json",

358 comment: "Required: plugin manifest",

359 },

360 ],

361 },

362 {

363 name: "skills/",

364 open: true,

365 children: [

366 {

367 name: "my-skill/",

368 open: true,

369 children: [

370 {

371 name: "SKILL.md",

372 comment: "Optional: skill instructions",

373 },

374 ],

375 },

376 ],

377 },

378 {

379 name: "hooks/",

380 open: true,

381 children: [

382 {

383 name: "hooks.json",

384 comment: "Optional: lifecycle hooks",

385 },

386 ],

387 },

388 {

389 name: ".app.json",

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

391 },

392 {

393 name: ".mcp.json",

394 comment: "Optional: MCP server configuration",

395 },

396 {

397 name: "assets/",

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

399 },

400 ],

401 },

402 ]}

403/>

323 404 

324Only `plugin.json` belongs in `.codex-plugin/`. Keep `skills/`, `assets/`,405Only `plugin.json` belongs in `.codex-plugin/`. Keep `skills/`, `hooks/`,

325`.mcp.json`, and `.app.json` at the plugin root.406`assets/`, `.mcp.json`, and `.app.json` at the plugin root.

326 407 

327Published plugins typically use a richer manifest than the minimal example that408Published plugins typically use a richer manifest than the minimal example that

328appears in quick-start scaffolds. The manifest has three jobs:409appears in quick-start scaffolds. The manifest has three jobs:

329 410 

330- Identify the plugin.411- Identify the plugin.

331- Point to bundled components such as skills, apps, or MCP servers.412- Point to bundled components such as skills, apps, MCP servers, or hooks.

332- Provide install-surface metadata such as descriptions, icons, and legal413- Provide install-surface metadata such as descriptions, icons, and legal

333 links.414 links.

334 415 

351 "skills": "./skills/",432 "skills": "./skills/",

352 "mcpServers": "./.mcp.json",433 "mcpServers": "./.mcp.json",

353 "apps": "./.app.json",434 "apps": "./.app.json",

435 "hooks": "./hooks/hooks.json",

354 "interface": {436 "interface": {

355 "displayName": "My Plugin",437 "displayName": "My Plugin",

356 "shortDescription": "Reusable skills and apps",438 "shortDescription": "Reusable skills and apps",

384- `name`, `version`, and `description` identify the plugin.466- `name`, `version`, and `description` identify the plugin.

385- `author`, `homepage`, `repository`, `license`, and `keywords` provide467- `author`, `homepage`, `repository`, `license`, and `keywords` provide

386 publisher and discovery metadata.468 publisher and discovery metadata.

387- `skills`, `mcpServers`, and `apps` point to bundled components relative to469- `skills`, `mcpServers`, `apps`, and `hooks` point to bundled components

388 the plugin root.470 relative to the plugin root.

389- `interface` controls how install surfaces present the plugin.471- `interface` controls how install surfaces present the plugin.

390 472 

391Use the `interface` object for install-surface metadata:473Use the `interface` object for install-surface metadata:

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

405- Store visual assets such as `composerIcon`, `logo`, and `screenshots` under487- Store visual assets such as `composerIcon`, `logo`, and `screenshots` under

406 `./assets/` when possible.488 `./assets/` when possible.

407- Use `skills` for bundled skill folders, `apps` for `.app.json`, and489- Use `skills` for bundled skill folders, `apps` for `.app.json`,

408 `mcpServers` for `.mcp.json`.490 `mcpServers` for `.mcp.json`, and `hooks` for lifecycle hooks.

491- Plugin hooks are off by default in this release; bundled hooks won't run

492 unless `[features].plugin_hooks = true`.

493- When plugin hooks are enabled, omit `hooks` to use the default

494 `./hooks/hooks.json` file when present.

495 

496### Bundled MCP servers and lifecycle hooks

497 

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

499server map or a wrapped `mcp_servers` object.

500 

501Direct server map:

502 

503```json

504{

505 "docs": {

506 "command": "docs-mcp",

507 "args": ["--stdio"]

508 }

509}

510```

511 

512Wrapped server map:

513 

514```json

515{

516 "mcp_servers": {

517 "docs": {

518 "command": "docs-mcp",

519 "args": ["--stdio"]

520 }

521 }

522}

523```

524 

525After installation, users can enable or disable a bundled MCP server and tune

526tool approval policy from their Codex config without editing the plugin. Use

527`plugins.<plugin>.mcp_servers.<server>` for plugin-scoped MCP server policy:

528 

529```toml

530[plugins."my-plugin".mcp_servers.docs]

531enabled = true

532default_tools_approval_mode = "prompt"

533enabled_tools = ["search"]

534 

535[plugins."my-plugin".mcp_servers.docs.tools.search]

536approval_mode = "approve"

537```

538 

539Plugin hooks are off by default in this release. When

540`[features].plugin_hooks = true` and your plugin is enabled, Codex can load

541lifecycle hooks from your plugin alongside user, project, and managed hooks.

542 

543```toml

544[features]

545plugin_hooks = true

546```

547 

548The default plugin hook file is `hooks/hooks.json`:

549 

550```json

551{

552 "hooks": {

553 "SessionStart": [

554 {

555 "hooks": [

556 {

557 "type": "command",

558 "command": "python3 ${PLUGIN_ROOT}/hooks/session_start.py",

559 "statusMessage": "Loading plugin context"

560 }

561 ]

562 }

563 ]

564 }

565}

566```

567 

568If you define `hooks` in `.codex-plugin/plugin.json`, Codex uses that manifest

569entry instead of the default `hooks/hooks.json`. The manifest field can be a

570single path, an array of paths, an inline hooks object, or an array of inline

571hooks objects.

572 

573```json

574{

575 "name": "repo-policy",

576 "hooks": ["./hooks/session.json", "./hooks/tools.json"]

577}

578```

579 

580Hook paths follow the same manifest path rules as `skills`, `apps`, and

581`mcpServers`: start with `./`, resolve relative to the plugin root, and stay

582inside the plugin root.

583 

584Plugin hook commands receive the Codex-specific environment variables

585`PLUGIN_ROOT` and `PLUGIN_DATA`. `PLUGIN_ROOT` points to the installed plugin

586root, and `PLUGIN_DATA` points to the plugin's writable data directory. Codex

587also sets `CLAUDE_PLUGIN_ROOT` and `CLAUDE_PLUGIN_DATA` for compatibility with

588existing plugin hooks.

589 

590Plugin hooks use the same event schema as regular hooks. See

591[Hooks](https://developers.openai.com/codex/hooks) for supported events, inputs, outputs, trust review, and

592current limitations.

409 593 

410### Publish official public plugins594### Publish official public plugins

411 595