plugins.md Codex Docs, 2026-03-27 00:39 UTC → 2026-04-07 00:40 UTC

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 

27![Codex plugin directory](/images/codex/plugins/directory.png)33![Codex Plugins page](/images/codex/plugins/directory.png)

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 

38![Plugin directory in Codex CLI](/images/codex/plugins/cli_light.png)44![Plugins list in Codex CLI](/images/codex/plugins/cli_light.png)

39 

40### Use plugins locally

41 

42For the fastest setup, use the built-in `@plugin-creator` skill to scaffold a

43local plugin.

44 

45![plugin-creator skill in Codex](/images/codex/plugins/plugin-creator.png)

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![how to invoke the plugin-creator skill](/images/codex/plugins/plugin-creator-invoke.png)

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![custom local marketplace in the plugin directory](/images/codex/plugins/codex-local-plugin-light.png)

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![Codex Plugins page](/images/codex/plugins/plugin-github-invoke.png)

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.