1# Plugins1# Plugins
2 2
3## What plugins are3## Overview
4 4
5Plugins are installable bundles for reusable Codex workflows. They make it5Plugins bundle skills, app integrations, and MCP servers into reusable
6easier to share the same setup across projects or teams, and they can package6workflows for Codex.
7skills, optional app integrations, and MCP server configurations in a single7
8place.8Extend what Codex can do, for example:
9
10- Install the Gmail plugin to let Codex read and manage Gmail.
11- Install the Google Drive plugin to work across Drive, Docs, Sheets, and
12 Slides.
13- Install the Slack plugin to summarize channels or draft replies.
9 14
10A plugin can contain:15A plugin can contain:
11 16
12- **Skills:** prompts that describe workflows to Codex and can be17- **Skills:** reusable instructions for specific kinds of work. Codex can load
13 progressively discovered by the agent.18 them when needed so it follows the right steps and uses the right references
14- **Apps:** optional app integrations or connector mappings packaged with the19 or helper scripts for a task.
15 plugin.20- **Apps:** connections to tools like GitHub, Slack, or Google Drive, so
16- **MCP servers:** remote tools or shared context the plugin needs.21 Codex can read information from those tools and take actions in them.
22- **MCP servers:** services that give Codex access to additional tools or
23 shared information, often from systems outside your local project.
17 24
18More plugin components are coming soon.25More plugin capabilities are coming soon.
19 26
20## Use and install plugins27## Use and install plugins
21 28
22### In the Codex app29### Plugin Directory in the Codex app
23 30
24Plugins curated by OpenAI appear in the Codex directory. Start there when you31Open **Plugins** in the Codex app to browse and install curated plugins.
25want ready-made workflows or app integrations.
26 32
2733
28 34
29### In the CLI35### Plugin directory in the CLI
30 36
31In Codex CLI, run the following command to open the plugins surface:37In Codex CLI, run the following command to open the plugins list:
32 38
33```text39```text
34codex40codex
35/plugins41/plugins
36```42```
37 43
3844
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 45
175The marketplace controls where Codex loads the plugin from. `source.path` can46### Install and use a plugin
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 47
181### How Codex uses marketplaces48Once you open the plugin directory:
182 49
183A plugin marketplace is a JSON catalog of plugins that Codex can read and501. Search or browse for a plugin, then open its details.
184install.512. Select the install button. In the app, select the plus button or
52 **Add to Codex**. In the CLI, select `Install plugin`.
533. If the plugin needs an external app, connect it when prompted. Some plugins
54 ask you to authenticate during install. Others wait until the first time you
55 use them.
564. After installation, start a new thread and ask Codex to use the plugin.
185 57
186Codex can read marketplace files from:58After you install a plugin, you can use it directly in the prompt window:
187 59
188- the curated marketplace that powers the official Plugin Directory60
189- a repo marketplace at `$REPO_ROOT/.agents/plugins/marketplace.json`
190- a personal marketplace at `~/.agents/plugins/marketplace.json`
191 61
192You can install any plugin exposed through a marketplace. Codex installs62Describe the task directly
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 63
198You can enable or disable each plugin individually. Codex stores each plugin’s64 Ask for the outcome you want, such as "Summarize unread Gmail threads
199on or off state in `~/.codex/config.toml`.65 from today" or "Pull the latest launch notes from Google Drive."
200 66
201## Build and distribute plugins67 Use this when you want Codex to choose the right installed tools for the
68 task.
202 69
203### When to create a plugin70Choose a specific plugin
204 71
205Use local skills when:72 Type <code>@</code> to invoke the plugin or one of its bundled skills
73 explicitly.
206 74
207- You are iterating on one repo or one workflow.75 Use this when you want to be specific about which plugin or skill Codex
208- The behavior is personal or project-specific.76should use. See [Codex app commands](https://developers.openai.com/codex/app/commands) and
209- You are experimenting before you package something reusable.77[Skills](https://developers.openai.com/codex/skills).
210 78
211Use plugins when:79### How permissions and data sharing work
212 80
213- You want the same skills or app integrations available across teams or81Installing a plugin makes its workflows available in Codex, but your existing
214 projects.82[approval settings](https://developers.openai.com/codex/agent-approvals-security) still apply. Any
215- You want to bundle skills, MCP config, and app integrations into one83connected external services remain subject to their own authentication,
216 installable unit.84privacy, and data-sharing policies.
217- You want a stable, versioned package for teammates or a marketplace.
218 85
219Start local, then package the workflow as a plugin when you are ready to share86- Bundled skills are available as soon as you install the plugin.
220it.87- If a plugin includes apps, Codex may prompt you to install or sign in to
88 those apps in ChatGPT during setup or the first time you use them.
89- If a plugin includes MCP servers, they may require additional setup or
90 authentication before you can use them.
91- When Codex sends data through a bundled app, that app's terms and privacy
92 policy apply.
221 93
222### Plugin structure94### Remove or turn off a plugin
223 95
224Every plugin has a manifest at `.codex-plugin/plugin.json`. It can also include96To remove a plugin, reopen it from the plugin browser and select
225a `skills/` directory, an `.app.json` file that points at one or more apps or97**Uninstall plugin**.
226connectors, and assets used to present the plugin across supported surfaces.
227 98
228- my-plugin/99Uninstalling a plugin removes the plugin bundle from Codex, but bundled apps
100stay installed until you manage them in ChatGPT.
229 101
230 - .codex-plugin/102If you want to keep a plugin installed but turn it off, set its entry in
103`~/.codex/config.toml` to `enabled = false`, then restart Codex:
231 104
232 - plugin.json Required: plugin manifest105```toml
233 - skills/106[plugins."gmail@openai-curated"]
234 107enabled = false
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```108```
305 109
306`my-first-plugin/.codex-plugin/plugin.json`110## Build your own plugin
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```
329name: hello
330description: Greet the user with a friendly message.
331
332Greet the user warmly and ask how you can help.
333```
334
3353. Follow [Use plugins locally](#use-plugins-locally) to load the plugin in
336 Codex.
337
338From there, you can add MCP config, app integrations, or marketplace metadata
339as needed.
340
341### Manifest fields
342
343Use the top-level fields to define package metadata and point to bundled
344components:
345
346- `name`, `version`, and `description` identify the plugin.
347- `author`, `homepage`, `repository`, `license`, and `keywords` provide
348 publisher and discovery metadata.
349- `skills`, `mcpServers`, and `apps` point to bundled components relative to
350 the plugin root.
351- `interface` controls how install surfaces present the plugin.
352
353Use the `interface` object for install-surface metadata:
354
355- `displayName`, `shortDescription`, and `longDescription` control the title and
356 descriptive copy.
357- `developerName`, `category`, and `capabilities` add publisher and capability
358 metadata.
359- `websiteURL`, `privacyPolicyURL`, and `termsOfServiceURL` provide external
360 links.
361- `defaultPrompt`, `brandColor`, `composerIcon`, `logo`, and `screenshots`
362 control starter prompts and visual presentation.
363
364### Path rules
365
366- Keep manifest paths relative to the plugin root and start them with `./`.
367- Store visual assets such as `composerIcon`, `logo`, and `screenshots` under
368 `./assets/` when possible.
369- Use `skills` for bundled skill folders, `apps` for `.app.json`, and
370 `mcpServers` for `.mcp.json`.
371
372### Publish official public plugins
373
374Adding plugins to the official Plugin Directory is coming soon.
375 111
376Self-serve plugin publishing and management are coming soon.112If you want to create, test, or distribute your own plugin, see
113[Build plugins](https://developers.openai.com/codex/plugins/build). That page covers local scaffolding,
114manual marketplace setup, plugin manifests, and packaging guidance.
