plugins.md Codex Docs, 2026-03-27 00:39 UTC → 2026-05-14 07:00 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<CodexScreenshot

34 alt="Codex Plugins page"

35 lightSrc="/images/codex/plugins/directory.png"

36 darkSrc="/images/codex/plugins/directory_dark.png"

37/>

28 38 

29### In the CLI39### Plugin directory in the CLI

30 40 

31In Codex CLI, run the following command to open the plugins surface:41In Codex CLI, run the following command to open the plugins list:

32 42 

33```text43```text

34codex44codex

35/plugins45/plugins

36```46```

37 47 

38![Plugin directory in Codex CLI](/images/codex/plugins/cli_light.png)48<CodexScreenshot

39 49 alt="Plugins list in Codex CLI"

40### Use plugins locally50 lightSrc="/images/codex/plugins/cli_light.png"

41 51 darkSrc="/images/codex/plugins/codex-plugin-cli.png"

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

43local plugin.53 

44 54The CLI plugin browser groups plugins by marketplace. Use the marketplace tabs

45![plugin-creator skill in Codex](/images/codex/plugins/plugin-creator.png)55to switch sources, open a plugin to inspect details, install or uninstall

46 56marketplace entries, and press <kbd>Space</kbd> on an installed plugin to toggle

47It creates the required `.codex-plugin/plugin.json` manifest and57its enabled state.

48can also generate a local marketplace entry for testing.58 

49 59### Install and use a plugin

50If you already have a plugin from another ecosystem or a plugin you built60 

51yourself, you can add it to your local marketplace with `@plugin-creator`.61Once you open the plugin directory:

52 62 

53![how to invoke the plugin-creator skill](/images/codex/plugins/plugin-creator-invoke.png)63<WorkflowSteps>

54 64 

55In the plugin directory, you can also load your own local marketplace with a651. Search or browse for a plugin, then open its details.

56custom marketplace name and browse the plugins there.662. Select the install button. In the app, select the plus button or

57 67 **Add to Codex**. In the CLI, select `Install plugin`.

58![custom local marketplace in the plugin directory](/images/codex/plugins/codex-local-plugin-light.png)683. If the plugin needs an external app, connect it when prompted. Some plugins

59 69 ask you to authenticate during install. Others wait until the first time you

60#### Install a local plugin manually70 use them.

61 714. After installation, start a new thread and ask Codex to use the plugin.

62Use a repo marketplace or a personal marketplace, depending on who should be72 

63able to access the plugin.73</WorkflowSteps>

64 74 

65Add a marketplace file at `$REPO_ROOT/.agents/plugins/marketplace.json`75After you install a plugin, you can use it directly in the prompt window:

66and store your plugins under `$REPO_ROOT/plugins/`.76 

67 77<CodexScreenshot

68**Repo marketplace example**78 alt="Codex Plugins page"

69 79 lightSrc="/images/codex/plugins/plugin-github-invoke.png"

70Step 1: Copy the plugin folder into `$REPO_ROOT/plugins/my-plugin`.80 darkSrc="/images/codex/plugins/plugin-github-invoke-dark.png"

71 81/>

72```82 

73mkdir -p ./plugins83<div class="not-prose mt-4 grid gap-4 md:grid-cols-2">

74cp -R /absolute/path/to/my-plugin ./plugins/my-plugin84 <div class="rounded-xl border border-subtle bg-surface px-5 py-4">

75```85 <p class="text-sm font-semibold text-default">Describe the task directly</p>

76 86 <p class="mt-2 text-sm text-secondary">

77Step 2: Add or update `$REPO_ROOT/.agents/plugins/marketplace.json` so87 Ask for the outcome you want, such as "Summarize unread Gmail threads

78that `source.path` points to that plugin directory with a `./`-prefixed88 from today" or "Pull the latest launch notes from Google Drive."

79relative path:89 </p>

80 90 <p class="mt-3 text-sm text-secondary">

81```91 Use this when you want Codex to choose the right installed tools for the

82{92 task.

83 "name": "local-repo",93 </p>

84 "plugins": [94 </div>

85 {95 

86 "name": "my-plugin",96 <div class="rounded-xl border border-subtle bg-surface px-5 py-4">

87 "source": {97 <p class="text-sm font-semibold text-default">Choose a specific plugin</p>

88 "source": "local",98 <p class="mt-2 text-sm text-secondary">

89 "path": "./plugins/my-plugin"99 Type <code>@</code> to invoke the plugin or one of its bundled skills

90 },100 explicitly.

91 "policy": {101 </p>

92 "installation": "AVAILABLE",102 <p class="mt-3 text-sm text-secondary">

93 "authentication": "ON_INSTALL"103 Use this when you want to be specific about which plugin or skill Codex

94 },104 should use. See <a href="/codex/app/commands">Codex app commands</a> and{" "}

95 "category": "Productivity"105 <a href="/codex/skills">Skills</a>.

96 }106 </p>

97 ]107 </div>

98}108</div>

99```109 

100 110### How permissions and data sharing work

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

102 112Installing a plugin makes its workflows available in Codex, but your existing

103Add a marketplace file at `~/.agents/plugins/marketplace.json` and store113[approval settings](https://developers.openai.com/codex/agent-approvals-security) still apply. Any

104your plugins under `~/.codex/plugins/`.114connected external services remain subject to their own authentication,

105 115privacy, and data-sharing policies.

106**Personal marketplace example**116 

107 117- Bundled skills are available as soon as you install the plugin.

108Step 1: Copy the plugin folder into `~/.codex/plugins/my-plugin`.118- If a plugin includes apps, Codex may prompt you to install or sign in to

109 119 those apps in ChatGPT during setup or the first time you use them.

110```120- If a plugin includes MCP servers, they may require additional setup or

111mkdir -p ~/.codex/plugins121 authentication before you can use them.

112cp -R /absolute/path/to/my-plugin ~/.codex/plugins/my-plugin122- When Codex sends data through a bundled app, that app's terms and privacy

113```123 policy apply.

114 124 

115Step 2: Add or update `~/.agents/plugins/marketplace.json` so that the125### Remove or turn off a plugin

116plugin entry’s `source.path` points to that directory.126 

117 127To remove a plugin, reopen it from the plugin browser and select

118Step 3: Restart Codex and verify that the plugin appears.128**Uninstall plugin**.

119 129 

120The marketplace file points to the plugin location, so those directories are130Uninstalling a plugin removes the plugin bundle from Codex, but bundled apps

121examples rather than fixed requirements. Codex resolves `source.path` relative131stay installed until you manage them in ChatGPT.

122to the marketplace root, not relative to the `.agents/plugins/` folder. See132 

123[Marketplace metadata](#marketplace-metadata) for the file format.133If you want to keep a plugin installed but turn it off, set its entry in

124 134`~/.codex/config.toml` to `enabled = false`, then restart Codex:

125After you change the plugin, update the plugin directory that your marketplace135 

126entry points to and restart Codex so the local install picks up the new files.136```toml

127 137[plugins."gmail@openai-curated"]

128### Marketplace metadata138enabled = false

129 139```

130If you maintain a repo marketplace, define it in140 

131`$REPO_ROOT/.agents/plugins/marketplace.json`. For a personal marketplace, use141## Build your own plugin

132`~/.agents/plugins/marketplace.json`. A marketplace file controls plugin142 

133ordering and install policies in Codex-facing catalogs. Before you add a plugin143If you want to create, test, or distribute your own plugin, see

134to a marketplace, make sure its `version`, publisher metadata, and144[Build plugins](https://developers.openai.com/codex/plugins/build). That page covers local scaffolding,

135install-surface copy are ready for other developers to see.145manual marketplace setup, plugin manifests, and packaging guidance.

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

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 

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