Codex Plugins: What They Are and How to Install One

A developer wants a plugin's workflow inside the terminal. The CLI path is short, but the final restart is easy to miss. Start a new session after installation.

What a Codex plugin contains

A plugin packages related capabilities so ChatGPT and Codex can load them as one workflow. Both products use one universal public plugin directory on their supported surfaces.

Plugins bundle capabilities into reusable workflows in ChatGPT and Codex. They can include skills and MCP servers.

Official wording: OpenAI, Plugins, read 4 November 2026, developers.openai.com

What a plugin can contain

Source: OpenAI, Plugins, read 4 November 2026.

A portable plugin has plugin.json at its root. It can also hold a skills/ directory, an mcp.json file and assets. Older .codex-plugin/plugin.json manifests remain supported as a compatibility fallback. Plugin hooks need review and trust before they run. For the separate hook setup, see the Codex hooks guide.

OpenAI uses its Codex Security plugin as an example for scanning authorized code and confirming plausible vulnerability findings. That is an example from the documentation, not a recommendation or a ranking.

Install a plugin in the Codex CLI

The CLI path has a short sequence, and the last move, a new session, is the one people miss.

Before you start

You need the Codex CLI and a marketplace that already lists the plugin. By the end, you will have one installed plugin whose bundled skills or tools load in a new session.

Start Codex, enter /plugins, open the plugin in its marketplace, install it, then start a new session and use it.

Step 1: Start Codex

Open a terminal in the repository where you want to work, then start the CLI.

codex

You should see: a Codex CLI session.

Step 2: Enter /plugins

Enter the command documented by OpenAI:

codex
/plugins

You should see: the plugin browser, grouped by marketplace.

Step 3: Open the plugin

Use the marketplace tabs to switch sources. Open the plugin to inspect its details before installing it.

You should see: the selected marketplace entry and its details.

Step 4: Install it

Choose the install action for that marketplace entry. Pressing Space on an installed plugin turns it on or off.

You should see: the plugin listed as installed.

Step 5: Start a new session

Close the current session and start a new one. Bundled skills become available only in a new chat or CLI session after installation.

You should see: the plugin's bundled skills or tools available in the new session.

If the plugin includes an MCP server, it may need extra setup or authentication. The Codex host's sandbox and approval policy still applies when the capability runs. A plugin that connects to an outside service also uses that service's own authentication and access controls. Some plugins are unavailable when you sign in with an OpenAI API key because their connection flow needs unsupported OAuth capabilities.

Add a marketplace from the CLI

Use codex plugin marketplace add to add and track a source. OpenAI documents these source forms:

codex plugin marketplace add owner/repo
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-root

A source can be GitHub shorthand, an HTTP or HTTPS Git URL, an SSH Git URL or a local marketplace root. The --ref option pins a Git ref. Repeat --sparse PATH for a sparse checkout of a Git-backed marketplace. The sparse option works only with Git sources.

Inspect, refresh or remove configured marketplaces with the documented commands:

codex plugin marketplace list
codex plugin marketplace upgrade
codex plugin marketplace upgrade marketplace-name
codex plugin marketplace remove marketplace-name

The list command prints every marketplace Codex is considering and its resolved root. If Codex cannot resolve one marketplace entry's source, it skips that entry rather than failing the whole marketplace.

OpenAI sends local-plugin installation and testing to the ChatGPT desktop app. The CLI path above is for plugins from configured marketplaces.

See the documented starter files

OpenAI's packaging page starts with this portable manifest:

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "my-first-plugin",
  "version": "1.0.0",
  "description": "Reusable greeting workflow"
}

The matching skill file goes under skills/<skill-name>/SKILL.md:

---
name: hello
description: Greet the user with a friendly message.
---

Greet the user warmly and ask how you can help.

A stable plugin name uses kebab case. Plugin hosts use it as the identifier and component namespace. Skills are discovered from the root skills/ directory, so the manifest does not need a skills field.

Our example: a small plugin and repo marketplace

Our example (illustrative).

The names and skill instructions below are ours, built only from the documented fields.

The repository contains these paths:

• plugins/team-plugin/plugin.json
• plugins/team-plugin/skills/team-summary/SKILL.md
• .agents/plugins/marketplace.json

The plugin manifest:

{
  "name": "team-plugin",
  "version": "1.0.0",
  "description": "Reusable team summary workflow"
}

The skill file:

---
name: team-summary
description: Turn project notes into a concise team summary.
---

Summarize the project notes, decisions, owners, and next actions.

The repository marketplace file:

{
  "name": "team-repo",
  "plugins": [
    {
      "name": "team-plugin",
      "source": {
        "source": "local",
        "path": "./plugins/team-plugin"
      },
      "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_INSTALL"
      },
      "category": "Productivity"
    }
  ]
}

Keep source.path relative to the marketplace root. It starts with ./ and stays inside that root. Codex resolves it from the marketplace root, not from the .agents/plugins/ folder. Each entry needs an installation policy, an authentication policy and a category.

Load it

Add the repository as a local marketplace root:

codex plugin marketplace add ./

OpenAI says to use the ChatGPT desktop app to install and test a local plugin. Restart the app, open the Plugins Directory, choose team-repo and install team-plugin. Then start a new session before asking for team-summary.

Turn a plugin on or off for one repo

The repository marketplace makes its plugins discoverable. Control a local-marketplace plugin for one project in .codex/config.toml:

[plugins."team-plugin@team-repo"]
enabled = true

The key is plugin-name@marketplace-name. Set enabled = false to disable the plugin for this project without uninstalling it. The plugin browser saves user-level choices in ~/.codex/config.toml. Project settings load only for trusted projects, and they override user, cloud-managed and system defaults subject to enforced requirements. These settings apply in Codex CLI and Codex in the ChatGPT desktop app.

Which Codex surface supports plugins?

Choose the host before you install. Plugin support differs by surface.

Plugin support by surface

Source: OpenAI, Plugins and Build plugins, read 4 November 2026.

Lifecycle hooks apply only to plugins installed manually in Codex desktop. Publishing a local plugin to your workspace does not put it in the universal public directory shared by ChatGPT and Codex.

Remove a plugin

Open the plugin in a supported browser and select Uninstall plugin when that action is available. Workspace-installed or default plugins may not offer it because the workspace administrator controls them. Uninstalling removes the bundle from that environment. A separately connected MCP server stays connected in ChatGPT until you disconnect it there.

If a plugin does not show up or does nothing

Start with the session and surface. Most first checks are quick and do not require rebuilding the plugin.

• Old session: start a new session so installed skills and tools can load.
• Wrong surface: use Codex CLI or the ChatGPT desktop app, not the IDE extension.
• API key limit: a plugin that needs an unsupported OAuth flow may not be available.
• MCP setup: complete the server's extra setup or authentication.
• Skipped marketplace entry: check whether its source resolves from the marketplace root.
• Project setting: trust the project and confirm the plugin is not set to enabled = false.

A team that publishes a plugin may also want to know how AI engines describe it. Xtrusio's free check shows when ChatGPT and Gemini mention you, which competitors appear instead and what to work on next.

Get your free AI visibility check

See when ChatGPT and Gemini mention you and which competitors appear instead with Xtrusio's free AI visibility check.

Sources

OpenAI and Xtrusio pages read 4 November 2026.

1. Plugins, OpenAI
2. Build plugins, OpenAI
3. Xtrusio home page, Xtrusio