plugins/build.md Codex Docs, 2026-05-02 06:45 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, lifecycle config,341file that points at one or more apps or connectors, an `.mcp.json` file that

308and assets used to present 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 - hooks/356 {

323 357 name: "plugin.json",

324 - hooks.json Optional: lifecycle configuration358 comment: "Required: plugin manifest",

325 - assets/ Optional: icons, logos, screenshots359 },

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

326 404 

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

328`.mcp.json`, `.app.json`, and lifecycle config files at the plugin root.406`assets/`, `.mcp.json`, and `.app.json` at the plugin root.

329 407 

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

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

332 410 

333- Identify the plugin.411- Identify the plugin.

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

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

336 links.414 links.

337 415 

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

410 `./assets/` when possible.488 `./assets/` when possible.

411- Use `skills` for bundled skill folders, `apps` for `.app.json`,489- Use `skills` for bundled skill folders, `apps` for `.app.json`,

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

413- If you omit `hooks` and the plugin includes `./hooks/hooks.json`, Codex loads491- Plugin hooks are off by default in this release; bundled hooks won't run

414 that default lifecycle config automatically.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.

415 495 

416### Bundled MCP servers and lifecycle config496### Bundled MCP servers and lifecycle hooks

417 497 

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

419server map or a wrapped `mcp_servers` object.499server map or a wrapped `mcp_servers` object.

442}522}

443```523```

444 524 

445`hooks` can point to one lifecycle JSON file, an array of lifecycle JSON files,525After installation, users can enable or disable a bundled MCP server and tune

446an inline lifecycle object, or an array of inline lifecycle objects. File paths526tool approval policy from their Codex config without editing the plugin. Use

447must follow the same `./`-prefixed plugin-root path rules as other manifest527`plugins.<plugin>.mcp_servers.<server>` for plugin-scoped MCP server policy:

448paths. If you omit the manifest field, Codex still checks `./hooks/hooks.json`.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.

449 593 

450### Publish official public plugins594### Publish official public plugins

451 595