plugins/build.md +454 −0 added
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
14
15It scaffolds the required `.codex-plugin/plugin.json` manifest and can also
16generate a local marketplace entry for testing. If you already have a plugin
17folder, you can still use `$plugin-creator` to wire it into a local
18marketplace.
19
20
21
22### Build your own curated plugin list
23
24A marketplace is a JSON catalog of plugins. `$plugin-creator` can generate one
25for a single plugin, and you can keep adding entries to that same marketplace
26to build your own curated list for a repo, team, or personal workflow.
27
28In Codex, each marketplace appears as a selectable source in the plugin
29directory. Use `$REPO_ROOT/.agents/plugins/marketplace.json` for a repo-scoped
30list or `~/.agents/plugins/marketplace.json` for a personal list. Add one
31entry per plugin under `plugins[]`, point each `source.path` at the plugin
32folder with a `./`-prefixed path relative to the marketplace root, and set
33`interface.displayName` to the label you want Codex to show in the marketplace
34picker. Then restart Codex. After that, open the plugin directory, choose your
35marketplace, and browse or install the plugins in that curated list.
36
37You don't need a separate marketplace per plugin. One marketplace can expose a
38single plugin while you are testing, then grow into a larger curated catalog as
39you add more plugins.
40
41
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
69### Create a plugin manually
70
71Start with a minimal plugin that packages one skill.
72
731. Create a plugin folder with a manifest at `.codex-plugin/plugin.json`.
74
75```bash
76mkdir -p my-first-plugin/.codex-plugin
77```
78
79`my-first-plugin/.codex-plugin/plugin.json`
80
81```json
82{
83 "name": "my-first-plugin",
84 "version": "1.0.0",
85 "description": "Reusable greeting workflow",
86 "skills": "./skills/"
87}
88```
89
90Use a stable plugin `name` in kebab-case. Codex uses it as the plugin
91identifier and component namespace.
92
932. Add a skill under `skills/<skill-name>/SKILL.md`.
94
95```bash
96mkdir -p my-first-plugin/skills/hello
97```
98
99`my-first-plugin/skills/hello/SKILL.md`
100
101```md
102---
103name: hello
104description: Greet the user with a friendly message.
105---
106
107Greet the user warmly and ask how you can help.
108```
109
1103. Add the plugin to a marketplace. Use `$plugin-creator` to generate one, or
111 follow [Build your own curated plugin list](#build-your-own-curated-plugin-list)
112 to wire the plugin into Codex manually.
113
114From there, you can add MCP config, app integrations, or marketplace metadata
115as needed.
116
117### Install a local plugin manually
118
119Use a repo marketplace or a personal marketplace, depending on who should be
120able to access the plugin or curated list.
121
122 Add a marketplace file at `$REPO_ROOT/.agents/plugins/marketplace.json`
123 and store your plugins under `$REPO_ROOT/plugins/`.
124
125 **Repo marketplace example**
126
127 Step 1: Copy the plugin folder into `$REPO_ROOT/plugins/my-plugin`.
128
129```bash
130mkdir -p ./plugins
131cp -R /absolute/path/to/my-plugin ./plugins/my-plugin
132```
133
134 Step 2: Add or update `$REPO_ROOT/.agents/plugins/marketplace.json` so
135 that `source.path` points to that plugin directory with a `./`-prefixed
136 relative path:
137
138```json
139{
140 "name": "local-repo",
141 "plugins": [
142 {
143 "name": "my-plugin",
144 "source": {
145 "source": "local",
146 "path": "./plugins/my-plugin"
147 },
148 "policy": {
149 "installation": "AVAILABLE",
150 "authentication": "ON_INSTALL"
151 },
152 "category": "Productivity"
153 }
154 ]
155}
156```
157
158 Step 3: Restart Codex and verify that the plugin appears.
159
160 Add a marketplace file at `~/.agents/plugins/marketplace.json` and store
161 your plugins under `~/.codex/plugins/`.
162
163 **Personal marketplace example**
164
165 Step 1: Copy the plugin folder into `~/.codex/plugins/my-plugin`.
166
167```bash
168mkdir -p ~/.codex/plugins
169cp -R /absolute/path/to/my-plugin ~/.codex/plugins/my-plugin
170```
171
172 Step 2: Add or update `~/.agents/plugins/marketplace.json` so that the
173 plugin entry's `source.path` points to that directory.
174
175 Step 3: Restart Codex and verify that the plugin appears.
176
177The marketplace file points to the plugin location, so those directories are
178examples rather than fixed requirements. Codex resolves `source.path` relative
179to the marketplace root, not relative to the `.agents/plugins/` folder. See
180[Marketplace metadata](#marketplace-metadata) for the file format.
181
182After you change the plugin, update the plugin directory that your marketplace
183entry points to and restart Codex so the local install picks up the new files.
184
185### Marketplace metadata
186
187If you maintain a repo marketplace, define it in
188`$REPO_ROOT/.agents/plugins/marketplace.json`. For a personal marketplace, use
189`~/.agents/plugins/marketplace.json`. A marketplace file controls plugin
190ordering and install policies in Codex-facing catalogs. It can represent one
191plugin while you are testing or a curated list of plugins that you want Codex
192to show together under one marketplace name. Before you add a plugin to a
193marketplace, make sure its `version`, publisher metadata, and install-surface
194copy are ready for other developers to see.
195
196```json
197{
198 "name": "local-example-plugins",
199 "interface": {
200 "displayName": "Local Example Plugins"
201 },
202 "plugins": [
203 {
204 "name": "my-plugin",
205 "source": {
206 "source": "local",
207 "path": "./plugins/my-plugin"
208 },
209 "policy": {
210 "installation": "AVAILABLE",
211 "authentication": "ON_INSTALL"
212 },
213 "category": "Productivity"
214 },
215 {
216 "name": "research-helper",
217 "source": {
218 "source": "local",
219 "path": "./plugins/research-helper"
220 },
221 "policy": {
222 "installation": "AVAILABLE",
223 "authentication": "ON_INSTALL"
224 },
225 "category": "Productivity"
226 }
227 ]
228}
229```
230
231- Use top-level `name` to identify the marketplace.
232- Use `interface.displayName` for the marketplace title shown in Codex.
233- Add one object per plugin under `plugins` to build a curated list that Codex
234 shows under that marketplace title.
235- Point each plugin entry's `source.path` at the plugin directory you want
236 Codex to load. For repo installs, that often lives under `./plugins/`. For
237 personal installs, a common pattern is `./.codex/plugins/<plugin-name>`.
238- Keep `source.path` relative to the marketplace root, start it with `./`, and
239 keep it inside that root.
240- For local entries, `source` can also be a plain string path such as
241 `"./plugins/my-plugin"`.
242- Always include `policy.installation`, `policy.authentication`, and
243 `category` on each plugin entry.
244- Use `policy.installation` values such as `AVAILABLE`,
245 `INSTALLED_BY_DEFAULT`, or `NOT_AVAILABLE`.
246- Use `policy.authentication` to decide whether auth happens on install or
247 first use.
248
249The marketplace controls where Codex loads the plugin from. A local
250`source.path` can point somewhere else if your plugin lives outside those
251example directories. A marketplace file can live in the repo where you are
252developing the plugin or in a separate marketplace repo, and one marketplace
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.
279
280### How Codex uses marketplaces
281
282A plugin marketplace is a JSON catalog of plugins that Codex can read and
283install.
284
285Codex can read marketplace files from:
286
287- the curated marketplace that powers the official Plugin Directory
288- a repo marketplace at `$REPO_ROOT/.agents/plugins/marketplace.json`
289- a Claude-style marketplace at `$REPO_ROOT/.claude-plugin/marketplace.json`
290- a personal marketplace at `~/.agents/plugins/marketplace.json`
291
292You can install any plugin exposed through a marketplace. Codex installs
293plugins into
294`~/.codex/plugins/cache/$MARKETPLACE_NAME/$PLUGIN_NAME/$VERSION/`. For local
295plugins, `$VERSION` is `local`, and Codex loads the installed copy from that
296cache path rather than directly from the marketplace entry.
297
298You can enable or disable each plugin individually. Codex stores each plugin's
299on or off state in `~/.codex/config.toml`.
300
301## Package and distribute plugins
302
303### Plugin structure
304
305Every 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 or
307connectors, an `.mcp.json` file that configures MCP servers, lifecycle config,
308and assets used to present the plugin across supported surfaces.
309
310- my-plugin/
311
312 - .codex-plugin/
313
314 - plugin.json Required: plugin manifest
315 - skills/
316
317 - my-skill/
318
319 - SKILL.md Optional: skill instructions
320 - .app.json Optional: app or connector mappings
321 - .mcp.json Optional: MCP server configuration
322 - hooks/
323
324 - hooks.json Optional: lifecycle configuration
325 - assets/ Optional: icons, logos, screenshots
326
327Only `plugin.json` belongs in `.codex-plugin/`. Keep `skills/`, `assets/`,
328`.mcp.json`, `.app.json`, and lifecycle config files at the plugin root.
329
330Published plugins typically use a richer manifest than the minimal example that
331appears in quick-start scaffolds. The manifest has three jobs:
332
333- Identify the plugin.
334- Point to bundled components such as skills, apps, or MCP servers.
335- Provide install-surface metadata such as descriptions, icons, and legal
336 links.
337
338Here's a complete manifest example:
339
340```json
341{
342 "name": "my-plugin",
343 "version": "0.1.0",
344 "description": "Bundle reusable skills and app integrations.",
345 "author": {
346 "name": "Your team",
347 "email": "team@example.com",
348 "url": "https://example.com"
349 },
350 "homepage": "https://example.com/plugins/my-plugin",
351 "repository": "https://github.com/example/my-plugin",
352 "license": "MIT",
353 "keywords": ["research", "crm"],
354 "skills": "./skills/",
355 "mcpServers": "./.mcp.json",
356 "apps": "./.app.json",
357 "hooks": "./hooks/hooks.json",
358 "interface": {
359 "displayName": "My Plugin",
360 "shortDescription": "Reusable skills and apps",
361 "longDescription": "Distribute skills and app integrations together.",
362 "developerName": "Your team",
363 "category": "Productivity",
364 "capabilities": ["Read", "Write"],
365 "websiteURL": "https://example.com",
366 "privacyPolicyURL": "https://example.com/privacy",
367 "termsOfServiceURL": "https://example.com/terms",
368 "defaultPrompt": [
369 "Use My Plugin to summarize new CRM notes.",
370 "Use My Plugin to triage new customer follow-ups."
371 ],
372 "brandColor": "#10A37F",
373 "composerIcon": "./assets/icon.png",
374 "logo": "./assets/logo.png",
375 "screenshots": ["./assets/screenshot-1.png"]
376 }
377}
378```
379
380`.codex-plugin/plugin.json` is the required entry point. The other manifest
381fields are optional, but published plugins commonly use them.
382
383### Manifest fields
384
385Use the top-level fields to define package metadata and point to bundled
386components:
387
388- `name`, `version`, and `description` identify the plugin.
389- `author`, `homepage`, `repository`, `license`, and `keywords` provide
390 publisher and discovery metadata.
391- `skills`, `mcpServers`, `apps`, and `hooks` point to bundled components
392 relative to the plugin root.
393- `interface` controls how install surfaces present the plugin.
394
395Use the `interface` object for install-surface metadata:
396
397- `displayName`, `shortDescription`, and `longDescription` control the title
398 and descriptive copy.
399- `developerName`, `category`, and `capabilities` add publisher and capability
400 metadata.
401- `websiteURL`, `privacyPolicyURL`, and `termsOfServiceURL` provide external
402 links.
403- `defaultPrompt`, `brandColor`, `composerIcon`, `logo`, and `screenshots`
404 control starter prompts and visual presentation.
405
406### Path rules
407
408- Keep manifest paths relative to the plugin root and start them with `./`.
409- Store visual assets such as `composerIcon`, `logo`, and `screenshots` under
410 `./assets/` when possible.
411- Use `skills` for bundled skill folders, `apps` for `.app.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`.
449
450### Publish official public plugins
451
452Adding plugins to the official Plugin Directory is coming soon.
453
454Self-serve plugin publishing and management are coming soon.