plugins/build.md Codex Docs, 2026-03-11 00:31 UTC → 2026-05-07 20:02 UTC

1# Build plugins

2 

3This page is for plugin authors. If you want to browse, install, and use

4plugins 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 plugin

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

7MCP config, or publish a stable package.

8 

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

10 

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

12 

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

18 

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

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

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

22marketplace.

23 

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

29 

30### Build your own curated plugin list

31 

32A marketplace is a JSON catalog of plugins. `$plugin-creator` can generate one

33for a single plugin, and you can keep adding entries to that same marketplace

34to build your own curated list for a repo, team, or personal workflow.

35 

36In Codex, each marketplace appears as a selectable source in the plugin

37directory. Use `$REPO_ROOT/.agents/plugins/marketplace.json` for a repo-scoped

38list or `~/.agents/plugins/marketplace.json` for a personal list. Add one

39entry per plugin under `plugins[]`, point each `source.path` at the plugin

40folder with a `./`-prefixed path relative to the marketplace root, and set

41`interface.displayName` to the label you want Codex to show in the marketplace

42picker. Then restart Codex. After that, open the plugin directory, choose your

43marketplace, and browse or install the plugins in that curated list.

44 

45You don't need a separate marketplace per plugin. One marketplace can expose a

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

47you add more plugins.

48 

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

80 

81### Create a plugin manually

82 

83Start with a minimal plugin that packages one skill.

84 

851. Create a plugin folder with a manifest at `.codex-plugin/plugin.json`.

86 

87```bash

88mkdir -p my-first-plugin/.codex-plugin

89```

90 

91`my-first-plugin/.codex-plugin/plugin.json`

92 

93```json

94{

95 "name": "my-first-plugin",

96 "version": "1.0.0",

97 "description": "Reusable greeting workflow",

98 "skills": "./skills/"

99}

100```

101 

102Use a stable plugin `name` in kebab-case. Codex uses it as the plugin

103identifier and component namespace.

104 

1052. Add a skill under `skills/<skill-name>/SKILL.md`.

106 

107```bash

108mkdir -p my-first-plugin/skills/hello

109```

110 

111`my-first-plugin/skills/hello/SKILL.md`

112 

113```md

114---

115name: hello

116description: Greet the user with a friendly message.

117---

118 

119Greet the user warmly and ask how you can help.

120```

121 

1223. Add the plugin to a marketplace. Use `$plugin-creator` to generate one, or

123 follow [Build your own curated plugin list](#build-your-own-curated-plugin-list)

124 to wire the plugin into Codex manually.

125 

126From there, you can add MCP config, app integrations, or marketplace metadata

127as needed.

128 

129### Install a local plugin manually

130 

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

132able to access the plugin or curated list.

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

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

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

152 

153 **Repo marketplace example**

154 

155 Step 1: Copy the plugin folder into `$REPO_ROOT/plugins/my-plugin`.

156 

157```bash

158mkdir -p ./plugins

159cp -R /absolute/path/to/my-plugin ./plugins/my-plugin

160```

161 

162 Step 2: Add or update `$REPO_ROOT/.agents/plugins/marketplace.json` so

163 that `source.path` points to that plugin directory with a `./`-prefixed

164 relative path:

165 

166```json

167{

168 "name": "local-repo",

169 "plugins": [

170 {

171 "name": "my-plugin",

172 "source": {

173 "source": "local",

174 "path": "./plugins/my-plugin"

175 },

176 "policy": {

177 "installation": "AVAILABLE",

178 "authentication": "ON_INSTALL"

179 },

180 "category": "Productivity"

181 }

182 ]

183}

184```

185 

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

187 

188 </div>

189 

190 <div slot="global">

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

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

193 

194 **Personal marketplace example**

195 

196 Step 1: Copy the plugin folder into `~/.codex/plugins/my-plugin`.

197 

198```bash

199mkdir -p ~/.codex/plugins

200cp -R /absolute/path/to/my-plugin ~/.codex/plugins/my-plugin

201```

202 

203 Step 2: Add or update `~/.agents/plugins/marketplace.json` so that the

204 plugin entry's `source.path` points to that directory.

205 

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

207 

208 </div>

209</Tabs>

210 

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

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

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

214[Marketplace metadata](#marketplace-metadata) for the file format.

215 

216After you change the plugin, update the plugin directory that your marketplace

217entry points to and restart Codex so the local install picks up the new files.

218 

219### Marketplace metadata

220 

221If you maintain a repo marketplace, define it in

222`$REPO_ROOT/.agents/plugins/marketplace.json`. For a personal marketplace, use

223`~/.agents/plugins/marketplace.json`. A marketplace file controls plugin

224ordering and install policies in Codex-facing catalogs. It can represent one

225plugin while you are testing or a curated list of plugins that you want Codex

226to show together under one marketplace name. Before you add a plugin to a

227marketplace, make sure its `version`, publisher metadata, and install-surface

228copy are ready for other developers to see.

229 

230```json

231{

232 "name": "local-example-plugins",

233 "interface": {

234 "displayName": "Local Example Plugins"

235 },

236 "plugins": [

237 {

238 "name": "my-plugin",

239 "source": {

240 "source": "local",

241 "path": "./plugins/my-plugin"

242 },

243 "policy": {

244 "installation": "AVAILABLE",

245 "authentication": "ON_INSTALL"

246 },

247 "category": "Productivity"

248 },

249 {

250 "name": "research-helper",

251 "source": {

252 "source": "local",

253 "path": "./plugins/research-helper"

254 },

255 "policy": {

256 "installation": "AVAILABLE",

257 "authentication": "ON_INSTALL"

258 },

259 "category": "Productivity"

260 }

261 ]

262}

263```

264 

265- Use top-level `name` to identify the marketplace.

266- Use `interface.displayName` for the marketplace title shown in Codex.

267- Add one object per plugin under `plugins` to build a curated list that Codex

268 shows under that marketplace title.

269- Point each plugin entry's `source.path` at the plugin directory you want

270 Codex to load. For repo installs, that often lives under `./plugins/`. For

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

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

273 keep it inside that root.

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

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

276- Always include `policy.installation`, `policy.authentication`, and

277 `category` on each plugin entry.

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

279 `INSTALLED_BY_DEFAULT`, or `NOT_AVAILABLE`.

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

281 first use.

282 

283The marketplace controls where Codex loads the plugin from. A local

284`source.path` can point somewhere else if your plugin lives outside those

285example directories. A marketplace file can live in the repo where you are

286developing the plugin or in a separate marketplace repo, and one marketplace

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.

313 

314### How Codex uses marketplaces

315 

316A plugin marketplace is a JSON catalog of plugins that Codex can read and

317install.

318 

319Codex can read marketplace files from:

320 

321- the curated marketplace that powers the official Plugin Directory

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

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

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

325 

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

327plugins into

328`~/.codex/plugins/cache/$MARKETPLACE_NAME/$PLUGIN_NAME/$VERSION/`. For local

329plugins, `$VERSION` is `local`, and Codex loads the installed copy from that

330cache path rather than directly from the marketplace entry.

331 

332You can enable or disable each plugin individually. Codex stores each plugin's

333on or off state in `~/.codex/config.toml`.

334 

335## Package and distribute plugins

336 

337### Plugin structure

338 

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

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

341connectors, an `.mcp.json` file that configures MCP servers, lifecycle config,

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

343 

344<FileTree

345 class="mt-4"

346 tree={[

347 {

348 name: "my-plugin/",

349 open: true,

350 children: [

351 {

352 name: ".codex-plugin/",

353 open: true,

354 children: [

355 {

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

403 

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

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

406 

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

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

409 

410- Identify the plugin.

411- Point to bundled components such as skills, apps, or MCP servers.

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

413 links.

414 

415Here's a complete manifest example:

416 

417```json

418{

419 "name": "my-plugin",

420 "version": "0.1.0",

421 "description": "Bundle reusable skills and app integrations.",

422 "author": {

423 "name": "Your team",

424 "email": "team@example.com",

425 "url": "https://example.com"

426 },

427 "homepage": "https://example.com/plugins/my-plugin",

428 "repository": "https://github.com/example/my-plugin",

429 "license": "MIT",

430 "keywords": ["research", "crm"],

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

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

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

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

435 "interface": {

436 "displayName": "My Plugin",

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

438 "longDescription": "Distribute skills and app integrations together.",

439 "developerName": "Your team",

440 "category": "Productivity",

441 "capabilities": ["Read", "Write"],

442 "websiteURL": "https://example.com",

443 "privacyPolicyURL": "https://example.com/privacy",

444 "termsOfServiceURL": "https://example.com/terms",

445 "defaultPrompt": [

446 "Use My Plugin to summarize new CRM notes.",

447 "Use My Plugin to triage new customer follow-ups."

448 ],

449 "brandColor": "#10A37F",

450 "composerIcon": "./assets/icon.png",

451 "logo": "./assets/logo.png",

452 "screenshots": ["./assets/screenshot-1.png"]

453 }

454}

455```

456 

457`.codex-plugin/plugin.json` is the required entry point. The other manifest

458fields are optional, but published plugins commonly use them.

459 

460### Manifest fields

461 

462Use the top-level fields to define package metadata and point to bundled

463components:

464 

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

466- `author`, `homepage`, `repository`, `license`, and `keywords` provide

467 publisher and discovery metadata.

468- `skills`, `mcpServers`, `apps`, and `hooks` point to bundled components

469 relative to the plugin root.

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

471 

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

473 

474- `displayName`, `shortDescription`, and `longDescription` control the title

475 and descriptive copy.

476- `developerName`, `category`, and `capabilities` add publisher and capability

477 metadata.

478- `websiteURL`, `privacyPolicyURL`, and `termsOfServiceURL` provide external

479 links.

480- `defaultPrompt`, `brandColor`, `composerIcon`, `logo`, and `screenshots`

481 control starter prompts and visual presentation.

482 

483### Path rules

484 

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

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

487 `./assets/` when possible.

488- Use `skills` for bundled skill folders, `apps` for `.app.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`.

526 

527### Publish official public plugins

528 

529Adding plugins to the official Plugin Directory is coming soon.

530 

531Self-serve plugin publishing and management are coming soon.