plugins.md +378 −0 added
1# Plugins
2
3## What plugins are
4
5Plugins are installable bundles for reusable Codex workflows. They make it
6easier to share the same setup across projects or teams, and they can package
7skills, optional app integrations, and MCP server configurations in a single
8place.
9
10A plugin can contain:
11
12- **Skills:** prompts that describe workflows to Codex and can be
13 progressively discovered by the agent.
14- **Apps:** optional app integrations or connector mappings packaged with the
15 plugin.
16- **MCP servers:** remote tools or shared context the plugin needs.
17
18More plugin components are coming soon.
19
20## Use and install plugins
21
22### In the Codex app
23
24Plugins curated by OpenAI appear in the Codex directory. Start there when you
25want ready-made workflows or app integrations.
26
27
28
29### In the CLI
30
31In Codex CLI, run the following command to open the plugins surface:
32
33```text
34codex
35/plugins
36```
37
38
39
40### Use plugins locally
41
42For the fastest setup, use the built-in `@plugin-creator` skill to scaffold a
43local plugin.
44
45
46
47It creates the required `.codex-plugin/plugin.json` manifest and
48can also generate a local marketplace entry for testing.
49
50If you already have a plugin from another ecosystem or a plugin you built
51yourself, you can add it to your local marketplace with `@plugin-creator`.
52
53
54
55In the plugin directory, you can also load your own local marketplace with a
56custom marketplace name and browse the plugins there.
57
58
59
60#### Install a local plugin manually
61
62Use a repo marketplace or a personal marketplace, depending on who should be
63able to access the plugin.
64
65Add a marketplace file at `$REPO_ROOT/.agents/plugins/marketplace.json`
66and store your plugins under `$REPO_ROOT/plugins/`.
67
68**Repo marketplace example**
69
70Step 1: Copy the plugin folder into `$REPO_ROOT/plugins/my-plugin`.
71
72```
73mkdir -p ./plugins
74cp -R /absolute/path/to/my-plugin ./plugins/my-plugin
75```
76
77Step 2: Add or update `$REPO_ROOT/.agents/plugins/marketplace.json` so
78that `source.path` points to that plugin directory with a `./`-prefixed
79relative path:
80
81```
82{
83 "name": "local-repo",
84 "plugins": [
85 {
86 "name": "my-plugin",
87 "source": {
88 "source": "local",
89 "path": "./plugins/my-plugin"
90 },
91 "policy": {
92 "installation": "AVAILABLE",
93 "authentication": "ON_INSTALL"
94 },
95 "category": "Productivity"
96 }
97 ]
98}
99```
100
101Step 3: Restart Codex and verify that the plugin appears.
102
103Add a marketplace file at `~/.agents/plugins/marketplace.json` and store
104your plugins under `~/.codex/plugins/`.
105
106**Personal marketplace example**
107
108Step 1: Copy the plugin folder into `~/.codex/plugins/my-plugin`.
109
110```
111mkdir -p ~/.codex/plugins
112cp -R /absolute/path/to/my-plugin ~/.codex/plugins/my-plugin
113```
114
115Step 2: Add or update `~/.agents/plugins/marketplace.json` so that the
116plugin entry’s `source.path` points to that directory.
117
118Step 3: Restart Codex and verify that the plugin appears.
119
120The marketplace file points to the plugin location, so those directories are
121examples rather than fixed requirements. Codex resolves `source.path` relative
122to the marketplace root, not relative to the `.agents/plugins/` folder. See
123[Marketplace metadata](#marketplace-metadata) for the file format.
124
125After you change the plugin, update the plugin directory that your marketplace
126entry points to and restart Codex so the local install picks up the new files.
127
128### Marketplace metadata
129
130If you maintain a repo marketplace, define it in
131`$REPO_ROOT/.agents/plugins/marketplace.json`. For a personal marketplace, use
132`~/.agents/plugins/marketplace.json`. A marketplace file controls plugin
133ordering and install policies in Codex-facing catalogs. Before you add a plugin
134to a marketplace, make sure its `version`, publisher metadata, and
135install-surface copy are ready for other developers to see.
136
137```
138{
139 "name": "openai-curated",
140 "interface": {
141 "displayName": "ChatGPT Official"
142 },
143 "plugins": [
144 {
145 "name": "my-plugin",
146 "source": {
147 "source": "local",
148 "path": "./plugins/my-plugin"
149 },
150 "policy": {
151 "installation": "AVAILABLE",
152 "authentication": "ON_INSTALL"
153 },
154 "category": "Productivity"
155 }
156 ]
157}
158```
159
160- Use top-level `name` to identify the marketplace.
161- Use `interface.displayName` for the marketplace title shown in Codex.
162- Point each plugin entry’s `source.path` at the plugin directory you want
163 Codex to load. For repo installs, that often lives under
164 `./plugins/`. For personal installs, it often lives under
165 `~/.codex/plugins/`.
166- Keep `source.path` relative to the marketplace root, start it with `./`, and
167 keep it inside that root.
168- Always include `policy.installation`, `policy.authentication`, and
169 `category` on each plugin entry.
170- Use `policy.installation` values such as `AVAILABLE`,
171 `INSTALLED_BY_DEFAULT`, or `NOT_AVAILABLE`.
172- Use `policy.authentication` to decide whether auth happens on install or
173 first use.
174
175The marketplace controls where Codex loads the plugin from. `source.path` can
176point somewhere else if your plugin lives outside those example directories. A
177marketplace file can live in the repo where you are developing the plugin or in
178a separate marketplace repo, and one marketplace file can point to one plugin
179or many.
180
181### How Codex uses marketplaces
182
183A plugin marketplace is a JSON catalog of plugins that Codex can read and
184install.
185
186Codex can read marketplace files from:
187
188- the curated marketplace that powers the official Plugin Directory
189- a repo marketplace at `$REPO_ROOT/.agents/plugins/marketplace.json`
190- a personal marketplace at `~/.agents/plugins/marketplace.json`
191
192You can install any plugin exposed through a marketplace. Codex installs
193plugins into
194`~/.codex/plugins/cache/$MARKETPLACE_NAME/$PLUGIN_NAME/$VERSION/`. For local
195plugins, `$VERSION` is `local`, and Codex loads the installed copy from that
196cache path rather than directly from the marketplace entry.
197
198You can enable or disable each plugin individually. Codex stores each plugin’s
199on or off state in `~/.codex/config.toml`.
200
201## Build and distribute plugins
202
203### When to create a plugin
204
205Use local skills when:
206
207- You are iterating on one repo or one workflow.
208- The behavior is personal or project-specific.
209- You are experimenting before you package something reusable.
210
211Use plugins when:
212
213- You want the same skills or app integrations available across teams or
214 projects.
215- You want to bundle skills, MCP config, and app integrations into one
216 installable unit.
217- You want a stable, versioned package for teammates or a marketplace.
218
219Start local, then package the workflow as a plugin when you are ready to share
220it.
221
222### Plugin structure
223
224Every plugin has a manifest at `.codex-plugin/plugin.json`. It can also include
225a `skills/` directory, an `.app.json` file that points at one or more apps or
226connectors, and assets used to present the plugin across supported surfaces.
227
228- my-plugin/
229
230 - .codex-plugin/
231
232 - plugin.json Required: plugin manifest
233 - skills/
234
235 - my-skill/
236
237 - SKILL.md Optional: skill instructions
238 - .app.json Optional: app or connector mappings
239 - .mcp.json Optional: MCP server configuration
240 - assets/ Optional: icons, logos, screenshots
241
242Only `plugin.json` belongs in `.codex-plugin/`. Keep `skills/`, `assets/`,
243`.mcp.json`, and `.app.json` at the plugin root.
244
245Published plugins typically use a richer manifest than the minimal example that
246appears in quick-start scaffolds. The manifest has three jobs:
247
248- Identify the plugin.
249- Point to bundled components such as skills, apps, or MCP servers.
250- Provide install-surface metadata such as descriptions, icons, and legal links.
251
252Here’s a complete manifest example:
253
254```
255{
256 "name": "my-plugin",
257 "version": "0.1.0",
258 "description": "Bundle reusable skills and app integrations.",
259 "author": {
260 "name": "Your team",
261 "email": "team@example.com",
262 "url": "https://example.com"
263 },
264 "homepage": "https://example.com/plugins/my-plugin",
265 "repository": "https://github.com/example/my-plugin",
266 "license": "MIT",
267 "keywords": ["research", "crm"],
268 "skills": "./skills/",
269 "mcpServers": "./.mcp.json",
270 "apps": "./.app.json",
271 "interface": {
272 "displayName": "My Plugin",
273 "shortDescription": "Reusable skills and apps",
274 "longDescription": "Distribute skills and app integrations together.",
275 "developerName": "Your team",
276 "category": "Productivity",
277 "capabilities": ["Read", "Write"],
278 "websiteURL": "https://example.com",
279 "privacyPolicyURL": "https://example.com/privacy",
280 "termsOfServiceURL": "https://example.com/terms",
281 "defaultPrompt": [
282 "Use My Plugin to summarize new CRM notes.",
283 "Use My Plugin to triage new customer follow-ups."
284 ],
285 "brandColor": "#10A37F",
286 "composerIcon": "./assets/icon.png",
287 "logo": "./assets/logo.png",
288 "screenshots": ["./assets/screenshot-1.png"]
289 }
290}
291```
292
293`.codex-plugin/plugin.json` is the required entry point. The other manifest
294fields are optional, but published plugins commonly use them.
295
296### Create your first plugin
297
298Start with a minimal plugin that packages one skill.
299
3001. Create a plugin folder with a manifest at `.codex-plugin/plugin.json`.
301
302```
303mkdir -p my-first-plugin/.codex-plugin
304```
305
306`my-first-plugin/.codex-plugin/plugin.json`
307
308```
309{
310 "name": "my-first-plugin",
311 "version": "1.0.0",
312 "description": "Reusable greeting workflow",
313 "skills": "./skills/"
314}
315```
316
317Use a stable plugin `name` in kebab-case. Codex uses it as the plugin
318identifier and component namespace.
319
3202. Add a skill under `skills/<skill-name>/SKILL.md`.
321
322```
323mkdir -p my-first-plugin/skills/hello
324```
325
326`my-first-plugin/skills/hello/SKILL.md`
327
328```
329---
330name: hello
331description: Greet the user with a friendly message.
332---
333
334Greet the user warmly and ask how you can help.
335```
336
3373. Follow [Use plugins locally](#use-plugins-locally) to load the plugin in
338 Codex.
339
340From there, you can add MCP config, app integrations, or marketplace metadata
341as needed.
342
343### Manifest fields
344
345Use the top-level fields to define package metadata and point to bundled
346components:
347
348- `name`, `version`, and `description` identify the plugin.
349- `author`, `homepage`, `repository`, `license`, and `keywords` provide
350 publisher and discovery metadata.
351- `skills`, `mcpServers`, and `apps` point to bundled components relative to
352 the plugin root.
353- `interface` controls how install surfaces present the plugin.
354
355Use the `interface` object for install-surface metadata:
356
357- `displayName`, `shortDescription`, and `longDescription` control the title and
358 descriptive copy.
359- `developerName`, `category`, and `capabilities` add publisher and capability
360 metadata.
361- `websiteURL`, `privacyPolicyURL`, and `termsOfServiceURL` provide external
362 links.
363- `defaultPrompt`, `brandColor`, `composerIcon`, `logo`, and `screenshots`
364 control starter prompts and visual presentation.
365
366### Path rules
367
368- Keep manifest paths relative to the plugin root and start them with `./`.
369- Store visual assets such as `composerIcon`, `logo`, and `screenshots` under
370 `./assets/` when possible.
371- Use `skills` for bundled skill folders, `apps` for `.app.json`, and
372 `mcpServers` for `.mcp.json`.
373
374### Publish official public plugins
375
376Adding plugins to the official Plugin Directory is coming soon.
377
378Self-serve plugin publishing and management are coming soon.