Plugins: Installing Bundles of Capabilities at Once
📚 Series Navigation: The previous article [22 Agent Skills] taught you how to write "specialized operations manuals" for Codex—where a skill instructs it: "handle this kind of task according to these steps." But as you write more, you will encounter an annoying issue: skills, MCP configurations, and app integrations are all separate pieces configured individually. This article teaches you how to package them into plugins (Plugins): to install, disable, and share them as a single bundle. The next article [24 Rules and Lifecycle Hooks (Hooks)] covers how to add "automatically triggered checkpoints" to Codex.
Everyone, today let's talk about something that sounds like a nice-to-have but is actually a must-have—plugins.
You might think, "isn't a plugin just a convenience of packaging, something optional I can worry about after mastering individual features?" To be honest, this judgment is exactly backward. I fell into this pitfall myself: in April 2025, I configured a set of skills for Codex in a project to "fetch database migrations and generate schema docs," alongside an MCP server to connect internal tools, which took me two hours. Two weeks later, I wanted to reuse the same setup in another repository—so I copied files from the old project one by one. I missed an environment variable configuration in .mcp.json, and the tool in the new project simply wouldn't connect. I spent another half-hour troubleshooting. Managing individual pieces is tiring and error-prone.
Plugins are Codex's official answer to this issue: packaging skills, app integrations, and MCP servers into a bundle that can be distributed and installed with one click. The capabilities you set up in project A can be installed in project B or on a colleague's machine all at once—no copying files, and no missing variables.
By reading this article, you will get:
- What three components a plugin packages, and how to choose between them and "loose skills," summarized in a table
- How to browse and install from the Plugin Directory (Plugin Directory), covering both the CLI and Desktop App paths
- How to add a marketplace from the CLI, install a plugin, and call it using
@, with commands and expected outputs - What the directory of a plugin package looks like (
.codex-plugin/plugin.json+ component directories), so you can follow it when packaging yourself - The trust check you must pass before installing third-party plugins and trusting hooks inside them
⚠️ Any specific commands, configuration options, directory paths, and default behaviors mentioned below are subject to the official Codex documentation. Model names, pricing, and "coming soon" indicators that change with versions are subject to what is actually displayed on your local system, and will not be hardcoded here.
01 Understand First: What Does a Plugin Package?
The bottom line: A plugin is a self-contained directory that packages reusable workflows—skills, app integrations, and MCP servers—allowing them to be installed, disabled, and shared as a single bundle.
Why do we need it? Because loose configurations introduce three pain points: difficulty in reusing across projects, manual team sharing, and no centralized updates. If you configure a skill and MCP in one project and want to reuse them elsewhere, you have to copy and paste them manually; sharing them with colleagues requires describing where each file goes and which config blocks to edit. A plugin packages this entire set into a single box, allowing you to move or share the box itself.
Analogy: IKEA's "packaged showroom rooms." If you like a study setup in a showroom—the desk, bookshelf, lamp, and storage boxes—and buy them individually, you have to find each product code, verify dimensions, and figure out the layout yourself. IKEA packages them into a "study set": a single order gets you everything, and assembling them according to the guide replicates the showroom setup. A Codex plugin follows this approach: packaging loose capabilities into a bundle to install them at once, saving you from configuring them individually.
The official docs state that plugins can contain three components, summarized in a table:
| Component | What it is | How to use it after installation |
|---|---|---|
| Skills (skills) | Reusable instructions for specific tasks; Codex loads them on demand and runs them with scripts | Codex matches them automatically based on task descriptions, or you call them explicitly with @ |
| Apps (apps) | Access channels to tools like GitHub, Slack, and Google Drive, allowing Codex to read info and perform tasks | Authorized in ChatGPT on installation or first use |
| MCP servers | Services connecting Codex to more tools or shared info, often from systems outside local projects | May require extra configuration or authentication before use |
Note that Codex plugins package these three components—skills, apps, and MCPs. This connects to the toolchain covered in previous articles: Article 22 taught you how to write skills, we discussed MCP previously, and app integration is how Codex connects to external services. A plugin bundles them together.
How do you choose between a plugin and a "loose skill"? The logic from the official documentation: if you are still iterating within a single repository and personal workflow, use local skills; if you want to share across teams, bundle app integrations and MCP configurations, or release stable versioned packages, use plugins.
| Dimension | Loose Skill (Local Use) | Plugin (plugin) |
|---|---|---|
| Best For | Single-repo personal use, individual workflows, fast testing | Sharing across teams, packaging apps + MCP, versioned releases |
| Components | Usually a single skill | skills + apps + MCP, plus lifecycle hooks |
| Sharing | Copying files manually to others | Sharing via marketplaces or workspaces for one-click installation |
| Versioning | Not emphasized | Has a version field for versioned releases |
The decision: for personal workflows, loose skills are enough; to share, bundle configurations, or publish versioned packages, use plugins. Do not build a plugin for a one-off skill.
💡 Summary in one sentence: A Codex plugin packages skills, app integrations, and MCP servers into a single bundle; use loose skills for personal workflows, and use plugins to share, bundle configurations, or release versioned packages.
02 Why Packaging into a Bundle is Better Than Loose Files
We covered what they are; now let's discuss why they are worth it—otherwise, you might still think, "copying a few files manually isn't that hard."
The difference lies in three areas, explained through concrete scenarios.
First: Reusing across projects. In the crash scenario I mentioned, switching projects meant copying skills/ and .mcp.json individually. If I missed a variable in the MCP config, the tool failed. With a plugin, you install it from the marketplace, and the entire setup is active without missing a single configuration.
Second: Sharing with the team. Sharing loose configurations with colleagues relies on instructions: "copy this folder, put skills here, and add this block to your config"—leading to configuration errors. With plugins: you publish it to a marketplace (even a private one for the repository) or share it directly in the Codex App with workspace members, and they install it with one click with identical settings.
Third: Centralized management and versioning. A plugin has a version field, making it a versioned package. Once installed, its switch, its MCP server, and its tool approvals can be managed individually in your Codex configuration without modifying the plugin itself. Changing loose configurations leaves users unaware, forcing you to notify everyone manually.
Analogy: Installing profile files on a phone. When a company configures a work phone, they don't ask you to manually set up Wi-Fi, email, VPNs, and certificates—they send you a "profile file." You tap it, and all settings write at once; deleting the profile removes them cleanly. A plugin is that profile file for your configurations—installed at once, managed centrally, and removed cleanly.
Comparing loose configs vs. plugins across these three tasks:
| Task | ❌ Loose Configs | ✅ Plugins |
|---|---|---|
| Reusing across projects | Copying files manually, risking missing MCP/variables | Installing from the marketplace, bringing the whole setup |
| Sharing with colleagues | Explaining where files go and what to change | Sharing in the workspace/marketplace for one-click install |
| Maintenance | No way to notify users on updates; manual notifications | Versioned releases; switches and approvals managed centrally |
To be honest, if you are working alone on a single project, the benefits of plugins aren't as obvious; once you have more people, projects, apps, and MCPs, loose files start to slow you down. Teams eventually shift completely to plugins—reducing onboarding setup for internal tools from thirty minutes of manual guides to a single install command.
💡 Summary in one sentence: The value of plugins lies in scale—reusing across projects, team sharing, and versioned maintenance are manual with loose files and one-click with plugins. The more people, projects, and configurations you have, the wider the gap.
03 The Plugin Directory: Codex's Built-in App Store
Once we know what they are, the next question is: where do I get plugins created by others? The answer is the "Plugin Directory (Plugin Directory)"—the built-in interface in Codex where you can browse and install.
It groups plugins into three sections:
Analogy: App store categories on a phone. One is "editor's choice" (curated officially for all users), one is "family sharing / team sharing" (shared with you by others in your workspace), and one is "my apps" (published or added by you). The Plugin Directory matches these:
| Section | What is inside |
|---|---|
| Curated by OpenAI (OpenAI Curated) | Selected by OpenAI, open to all Codex users—the most stable |
| Shared with you (Shared with you) | Shared with you by other members of your ChatGPT workspace |
| Created by you (Created by you) | Created by you, or added to your workspace |
You can browse and install via the Desktop App or the CLI:
Desktop App: Open the Plugins panel in the Codex App to browse, search, and install curated plugins. Click the add button or Add to Codex to install.
CLI: Launch Codex and run the following command to open the plugin browser (note the plural plugins):
codex
/pluginsThe CLI plugin browser groups by "marketplaces," allowing you to switch sources with tabs. Select a plugin to view details, install, or uninstall; press Space on an installed plugin to toggle its enabled state (keeping it installed but temporarily disabled).
How do you use it after installation? The official docs provide two ways:
- Describe the desired output. For example: "summarize today's unread emails in Gmail" or "fetch the latest release notes from Google Drive"—describe the task and let Codex choose the installed tool.
- Call the plugin or its skill using
@. If you know which plugin and skill to use, type@to invoke it explicitly without letting Codex guess.
You should recognize this @ prefix—it is the same prefix used for explicit calls in Article 22. Calling skills packaged in plugins is identical to calling loose skills, except they come from a plugin bundle.
💡 Summary in one sentence: The Plugin Directory is Codex's built-in app store, containing "OpenAI Curated, Shared with you, and Created by you" sections; browse and install via Plugins in the App or
/pluginsin the CLI, and invoke by describing tasks or using@.
04 Installing a Plugin: Permissions and Data Flows
Is clicking "install" in /plugins the end of it? Not quite—we must explain that "installing a plugin does not mean granting it free rein." This is where beginners often make assumptions.
The official docs state the rule clearly: installing a plugin makes its workflows available in Codex, but your existing approvals configurations still govern it. In other words, a plugin does not bypass the permissions from Article 15 or the safety boundaries from Article 16.
For the three components, the activation flows differ:
| Component | After Installation |
|---|---|
| Skills | Immediately active after installation, requiring no extra authorization |
| Apps | May prompt you to install or log in to the app in ChatGPT on installation or first use |
| MCP servers | May require extra configuration or authentication before use |
Notice: skills are active immediately, while apps and MCPs may require an extra step of authorization. When you install a plugin, identify its components to know if extra authorizations are needed.
Also, a rule regarding data: when Codex sends data through an app packaged in a plugin, that app's own terms and privacy policy apply. This means how data is handled by external services (GitHub, Slack, Drive) follows their respective policies, directly linking to whether you trust that external service.
Analogy: Authorizing a smart lock app on your phone in stages. You install a smart home App (plugin installed), but to link it to the door lock, you must scan a QR code to pair them (first-use authorization of the app integration); to use its cloud video storage, you must log in to that account (extra authentication for MCP). Installing the App is one step, while granting permissions to individual external devices consists of other steps—the plugin permissions model works this way: installation is distinct from authorization.
To remove a plugin, choose one of two ways:
- Uninstall completely: Open it in the plugin browser and select Uninstall plugin. Note—uninstalling only removes the plugin itself; the apps installed in ChatGPT remain, and must be managed in ChatGPT separately.
- Keep but disable: To keep the plugin but stop using it temporarily, set
enabled = falsein~/.codex/config.toml(your user-level config file) and restart Codex:
[plugins."gmail@openai-curated"]
enabled = falseNote the key format—plugin_name@marketplace_name, where gmail is the plugin and openai-curated is the marketplace. Pressing Space on an installed plugin in the CLI toggles its enabled state, which writes this configuration.
💡 Summary in one sentence: Installing a plugin does not bypass permissions—skills are active immediately, while apps and MCPs require individual authorizations, and existing approvals configurations still govern the plugin; uninstalling only removes the local plugin, and you can disable it in
config.tomlusingenabled = falsefollowed by a restart.
05 Hands-on: Add a Marketplace, Install a Plugin, and Use It
Practice makes perfect. Below, we add a marketplace from the CLI, install a local plugin, and call it using @. It does not depend on complex environments.
Unlike clicking in the Desktop App, managing marketplaces in the CLI uses the codex plugin marketplace commands—these are terminal commands, not slash commands in the session, so do not mix them up.
Step 1: Add a marketplace
We add it from GitHub. Replace owner/repo with the actual GitHub repository name:
codex plugin marketplace add owner/repoThe system supports other sources and parameters as well:
codex plugin marketplace add owner/repo --ref main
codex plugin marketplace add https://github.com/example/plugins.git --sparse .agents/plugins
codex plugin marketplace add ./local-marketplace-rootSources can be GitHub shortcuts (owner/repo or owner/repo@ref), HTTP/HTTPS Git URLs, SSH Git URLs, or local marketplace root directories. --ref pins a Git ref; --sparse PATH runs a sparse checkout on Git marketplace repositories, valid only for Git sources.
Expected: Codex registers the marketplace, which then appears as a source in the plugin browser. This step does not install plugins; it only adds the shelves to your store.
Step 2: Check registered marketplaces
codex plugin marketplace listExpected: Lists each marketplace Codex considers along with its resolved root paths—including the local default marketplace and configured marketplace snapshots. Verify your added marketplace appears in the list.
Other marketplace management commands (keep them in mind for later use):
codex plugin marketplace upgrade # Refresh all marketplaces
codex plugin marketplace upgrade marketplace-name # Refresh a specific marketplace
codex plugin marketplace remove marketplace-name # Remove a specific marketplaceStep 3: Open the plugin browser and install a plugin
Enter a session and open the plugin browser:
codex
/pluginsExpected: The plugin browser pops up grouped by marketplaces. Switch to your added marketplace, select a plugin, and click Install plugin.
Step 4: Call the plugin using @
The official docs state: after installing a plugin, open a new thread (new thread) before letting Codex use it. Then describe the task in the input box, or type @ to name the plugin or its skill:
@<plugin_or_skill_name>Expected: Codex invokes the plugin's capability. If it includes apps or MCPs, it may prompt you to authorize in ChatGPT or authenticate—follow the prompts to complete setup.
Running these steps verifies the flow: adding a marketplace → installing a plugin → invoking it. The Desktop App wraps these steps in a graphical interface.
⚠️ If you cannot invoke it with
@after installation, verify you opened a new thread first (required by the system); for apps/MCPs, verify the authorization step was completed.
💡 Summary in one sentence: Add marketplaces using
codex plugin marketplace addin the terminal, select Install in/pluginsto install, and open a new thread to invoke via descriptions or@names—running this flow is key to mastering plugins.
06 Packaging Your Own: Plugin Directory Structure
We have used plugins created by others, but you will eventually want to package your skills and MCP configurations into plugins. This section does not cover building a publishing-ready plugin (which is a larger task), but rather introduces the directory structure so you know what it looks like.
The easiest way is using the built-in @plugin-creator skill, dedicated to building plugin skeletons—it generates the required .codex-plugin/plugin.json manifest and sets up a local marketplace entry for testing. If you already have a plugin folder, you can use it to link the plugin to your local marketplace. Use it as your starting point.
Manually, a plugin consists of two parts: a manifest file acting as the ID + component directories.
The manifest is .codex-plugin/plugin.json, looking like this in its minimal form:
{
"name": "my-first-plugin",
"version": "1.0.0",
"description": "Reusable greeting workflow",
"skills": "./skills/"
}name is the most critical field—it acts as the plugin identifier and component namespace. The system requires kebab-case (lowercase with hyphens, e.g., my-first-plugin) for stability. The fields skills, mcpServers, apps, and hooks point to their respective components, using paths relative to the plugin root starting with ./.
The component directories sit in the plugin root. Arrange them according to the official convention table:
| Component | Placed Where | Manifest Field |
|---|---|---|
| skill | skills/<name>/SKILL.md | skills |
| Lifecycle hook | hooks/hooks.json | hooks (defaults can be omitted) |
| MCP server config | .mcp.json in root | mcpServers |
| app / connector | .app.json in root | apps |
| Images, screenshots, etc. | under ./assets/ | referenced in interface |
The structure of the plugin directory:
my-first-plugin/
├── .codex-plugin/
│ └── plugin.json ← Manifest, the only file placed here
├── skills/
│ └── hello/
│ └── SKILL.md
├── .mcp.json ← MCP config in root
├── .app.json ← app integration in root
└── hooks/
└── hooks.jsonHere is a critical rule repeatedly emphasized in the official docs:
Only
plugin.jsonbelongs under.codex-plugin/. Placeskills/,hooks/,assets/,.mcp.json, and.app.jsonat the plugin root level.
Simply put: the .codex-plugin/ directory must contain only plugin.json. Other component directories go to the plugin root, parallel to .codex-plugin/. A common pitfall is placing skills/ inside .codex-plugin/, which loads the plugin but prevents the skills from appearing.
Two default settings to keep in mind:
- Hooks can omit fields if using default paths. If your hooks reside at
./hooks/hooks.json, you don't need to define thehooksfield in the manifest; Codex scans this default path automatically. - Production manifests are richer. Manifests built for publishing typically include
author,homepage, andlicense, as well as aninterfaceobject (managing display names, descriptions, icons, branding colors, and starter prompts in the store). These fields are optional; a minimal manifest is sufficient for testing.
You might notice this directory structure matches skill paths and MCP .mcp.json files. This is by design—plugins collect loose configurations into a self-contained directory. This is why the docs recommend starting with local skills and shifting to plugins when you want to share.
💡 Summary in one sentence: A plugin consists of
.codex-plugin/plugin.json(the identifier manifest, using kebab-case for namespaces) + component directories at the root; remember the rule:.codex-plugin/contains onlyplugin.json, while skills / hooks /.mcp.json/.app.jsonreside at the root; start with@plugin-creatorfor skeletons.
07 The Trust Check: Plugins Run Code, and Hooks Require Explicit Approvals
This is the most critical safety section to master. All conveniences depend on a single prerequisite: you trust the source of the plugin.
Recall the safety judgment from Article 16—you must apply it to plugins. A plugin can bring app integrations (reading/writing your external accounts), MCP servers (executing tools), and lifecycle hooks (running scripts on events). These act within your permissions boundaries.
However, Codex includes a design—hooks inside plugins are not trusted automatically just because you installed and enabled the plugin. The official text states:
Installing or enabling a plugin does not automatically trust its hooks. Hooks packaged in plugins are treated as non-managed hooks, so Codex skips them until the user reviews and trusts the hook definition.
What does this mean? Even if you accidentally install a plugin containing a malicious hook, that hook will not execute immediately—Codex blocks it, waiting until you review the hook definition and explicitly trust it. This "install does not mean trust" gate is the most critical safety layer in plugins. We will cover hook events and trust review mechanisms in detail in Article 24 Rules and Lifecycle Hooks (Hooks); for now, keep this block in mind.
Analogy: Receiving a smart speaker from a stranger; plugging it in does not connect it. You receive a smart speaker of an unknown brand and plug it in. It lights up (plugin installed, skills active), but to let it connect to your home Wi-Fi or access your accounts, you must explicitly click "allow" in the app—otherwise, it remains an isolated box, unable to touch your network or data. Hooks in plugins are the same: they are imported, but "allowing them to run automatically" requires your explicit approval.
Three rules of thumb for checking third-party plugins before installation:
| Check | How to do it |
|---|---|
| Is the source trusted? | Prefer the OpenAI Curated section; for workspace-shared plugins, check who shared them; avoid adding marketplaces of unknown public repositories |
| What does it package? | Check the plugin details before installation to see if it includes apps / MCPs / hooks, indicating its permissions scope |
| Have you reviewed hooks? | For plugins containing hooks, read the hook definitions when Codex prompts for trust, and do not approve blindly |
Several official safety designs: workspace-shared plugins stay within your workspace and organization boundaries, inaccessible to accounts outside the organization; hooks are untrusted by default, requiring your review; installing plugins does not bypass existing approvals configurations. None of these, however, replace your own judgment—install only from trusted sources.
A note on the current status: the official docs state that publishing plugins to the public directory and self-service management are "coming soon." Currently, third-party plugins are distributed via "repository marketplaces" and "workspace sharing," keeping sources relatively controlled—you will mostly install plugins from your team or trusted parties, rather than an open public directory.
💡 Summary in one sentence: Plugins introduce apps, MCPs, and hooks to your permissions scope, but Codex includes a safety gate—hooks inside plugins are untrusted by default and run only after your review; check the source, package components, and hook definitions of third-party plugins, and stick to OpenAI Curated for safety.
08 Summary
We have explored Codex plugins—packages bundling skills, app integrations, and MCP servers to install, manage, and version-control them as a single kit.
Let's review the key points:
| Objective | Tool / Method | Key Takeaway |
|---|---|---|
| What is a plugin? | Bundle of skills + apps + MCP | Use loose skills for single-repo personal use, and plugins to share, bundle configs, or version releases |
| Finding plugins | Plugin Directory | Curated by OpenAI / Shared with you / Created by you |
| Browsing & Installing | Plugins panel in App / /plugins in CLI | Add marketplaces in terminal with codex plugin marketplace add |
| Calling plugins | Descriptions or @ names | Open a new thread after install; apps/MCPs may prompt for authorizations |
| Disabling | config.toml | Set [plugins."name@marketplace"] enabled = false and restart |
| Packaging | Manifest + component directories | .codex-plugin/ contains only plugin.json; start with @plugin-creator |
| Third-party | Trust check | Plugins bring apps/MCP/hooks; hooks are untrusted by default and require review |
The diagram below connects the two lines: the "add marketplace → install → invoke" user flow on top, and the packaged components and hooks along with their activation scopes on the bottom.
This diagram outlines the system: the top row is the four-step user flow from adding marketplaces to invoking; the bottom row is the packaged components in a plugin—three components plus hooks, each marked with its activation requirements, showing which are ready out-of-the-box and which require your approval.
You should now be able to: choose between plugins and loose skills; install pre-made capabilities via "add marketplace → install → @ invoke"; understand the authorization gates for apps/MCPs/hooks; identify a plugin's directory structure; and apply the trust check before installing third-party plugins and approving hooks. This setup allows you to leverage packaged capabilities from the marketplace, ready to use.
From AGENTS.md in Article 11, to MCP, to skills in Article 22, and now plugins for managing them together—your Codex customization toolkit is complete.
The next article [24 Rules and Lifecycle Hooks (Hooks)]—in this article we mentioned that "hooks in plugins are untrusted by default, running only after your review," but what exactly is a hook, which events can it check, and what does the "trust review" look like? The next article covers it: how to add automatically triggered checkpoints to Codex—running scripts automatically when it reads files, runs commands, or starts sessions, converting rules from "relying on its self-discipline" to "machine-enforced." Think about it: if checking before commits ran automatically instead of you remembering to run it, wouldn't that give you peace of mind?