plugins.md +145 −0 added
1# Plugins
2
3## Overview
4
5Plugins bundle skills, app integrations, and MCP servers into reusable
6workflows for Codex.
7
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.
14
15A plugin can contain:
16
17- **Skills:** reusable instructions for specific kinds of work. Codex can load
18 them when needed so it follows the right steps and uses the right references
19 or helper scripts for a task.
20- **Apps:** connections to tools like GitHub, Slack, or Google Drive, so
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.
24
25More plugin capabilities are coming soon.
26
27## Use and install plugins
28
29### Plugin Directory in the Codex app
30
31Open **Plugins** in the Codex app to browse and install curated plugins.
32
33<CodexScreenshot
34 alt="Codex Plugins page"
35 lightSrc="/images/codex/plugins/directory.png"
36 darkSrc="/images/codex/plugins/directory_dark.png"
37/>
38
39### Plugin directory in the CLI
40
41In Codex CLI, run the following command to open the plugins list:
42
43```text
44codex
45/plugins
46```
47
48<CodexScreenshot
49 alt="Plugins list in Codex CLI"
50 lightSrc="/images/codex/plugins/cli_light.png"
51 darkSrc="/images/codex/plugins/codex-plugin-cli.png"
52/>
53
54The CLI plugin browser groups plugins by marketplace. Use the marketplace tabs
55to switch sources, open a plugin to inspect details, install or uninstall
56marketplace entries, and press <kbd>Space</kbd> on an installed plugin to toggle
57its enabled state.
58
59### Install and use a plugin
60
61Once you open the plugin directory:
62
63<WorkflowSteps>
64
651. Search or browse for a plugin, then open its details.
662. Select the install button. In the app, select the plus button or
67 **Add to Codex**. In the CLI, select `Install plugin`.
683. If the plugin needs an external app, connect it when prompted. Some plugins
69 ask you to authenticate during install. Others wait until the first time you
70 use them.
714. After installation, start a new thread and ask Codex to use the plugin.
72
73</WorkflowSteps>
74
75After you install a plugin, you can use it directly in the prompt window:
76
77<CodexScreenshot
78 alt="Codex Plugins page"
79 lightSrc="/images/codex/plugins/plugin-github-invoke.png"
80 darkSrc="/images/codex/plugins/plugin-github-invoke-dark.png"
81/>
82
83<div class="not-prose mt-4 grid gap-4 md:grid-cols-2">
84 <div class="rounded-xl border border-subtle bg-surface px-5 py-4">
85 <p class="text-sm font-semibold text-default">Describe the task directly</p>
86 <p class="mt-2 text-sm text-secondary">
87 Ask for the outcome you want, such as "Summarize unread Gmail threads
88 from today" or "Pull the latest launch notes from Google Drive."
89 </p>
90 <p class="mt-3 text-sm text-secondary">
91 Use this when you want Codex to choose the right installed tools for the
92 task.
93 </p>
94 </div>
95
96 <div class="rounded-xl border border-subtle bg-surface px-5 py-4">
97 <p class="text-sm font-semibold text-default">Choose a specific plugin</p>
98 <p class="mt-2 text-sm text-secondary">
99 Type <code>@</code> to invoke the plugin or one of its bundled skills
100 explicitly.
101 </p>
102 <p class="mt-3 text-sm text-secondary">
103 Use this when you want to be specific about which plugin or skill Codex
104 should use. See <a href="/codex/app/commands">Codex app commands</a> and{" "}
105 <a href="/codex/skills">Skills</a>.
106 </p>
107 </div>
108</div>
109
110### How permissions and data sharing work
111
112Installing a plugin makes its workflows available in Codex, but your existing
113[approval settings](https://developers.openai.com/codex/agent-approvals-security) still apply. Any
114connected external services remain subject to their own authentication,
115privacy, and data-sharing policies.
116
117- Bundled skills are available as soon as you install the plugin.
118- If a plugin includes apps, Codex may prompt you to install or sign in to
119 those apps in ChatGPT during setup or the first time you use them.
120- If a plugin includes MCP servers, they may require additional setup or
121 authentication before you can use them.
122- When Codex sends data through a bundled app, that app's terms and privacy
123 policy apply.
124
125### Remove or turn off a plugin
126
127To remove a plugin, reopen it from the plugin browser and select
128**Uninstall plugin**.
129
130Uninstalling a plugin removes the plugin bundle from Codex, but bundled apps
131stay installed until you manage them in ChatGPT.
132
133If you want to keep a plugin installed but turn it off, set its entry in
134`~/.codex/config.toml` to `enabled = false`, then restart Codex:
135
136```toml
137[plugins."gmail@openai-curated"]
138enabled = false
139```
140
141## Build your own plugin
142
143If you want to create, test, or distribute your own plugin, see
144[Build plugins](https://developers.openai.com/codex/plugins/build). That page covers local scaffolding,
145manual marketplace setup, plugin manifests, and packaging guidance.