Codex plugins: install, marketplaces and building your own

What are Codex plugins?

Codex plugins are installable packages that add skills, MCP servers and other capabilities to Codex in one step. OpenAI's plugins documentation puts it this way: "Plugins bundle capabilities into reusable workflows in ChatGPT and Codex." You install them from a marketplace, and their skills and tools appear in your next session.

ChatGPT and Codex share one public plugin directory, so a public plugin you find in one shows up in the other. OpenAI's examples include a Codex Security plugin for scanning authorized code, plus Gmail, Google Drive and Slack plugins.

A plugin can contain one or more of these parts:

• Skills: reusable instructions for a kind of task, with optional references or helper scripts. These are the same SKILL.md folders described in our Codex skills guide.
• MCP servers: connections to systems such as GitHub, Slack or Google Drive. They define tools, handle authentication and can include custom UI. See Codex MCP for the standalone setup.
• Browser extensions: browser capabilities a plugin's workflow needs.
• Hooks: commands that run at set points in the Codex runtime. You must review and trust them before they run.

Where can you use plugins?

Support depends on the surface, per OpenAI's docs:

If you sign in to Codex with an API key instead of a ChatGPT account, you can still browse and install supported OpenAI-curated plugins in the CLI and desktop app. Some plugins are not available that way because their connection flows need OAuth capabilities that API key sign-in does not support.

How do you install a plugin in Codex CLI?

Open Codex and type the slash command:

codex
/plugins

The plugin browser groups plugins by marketplace. Use the tabs to switch sources, open a plugin to see its details, and install it. Then start a new session: bundled skills and tools only load in sessions that start after installation.

In the same browser you can press Space on an installed plugin to turn it on or off, and uninstall plugins you no longer want. Plugins your workspace installed or set as defaults may not offer an uninstall option, because an admin controls them.

Two things to know after installing:

• MCP servers may need setup. Some plugins ask you to sign in to a service during install, others on first use.
• Your sandbox rules still apply. When a plugin runs through Codex, the host's sandbox and approval policy applies. External services keep their own access controls.

Uninstalling removes the plugin bundle, but separately connected MCP integrations stay connected in ChatGPT until you disconnect them there.

How do plugin marketplaces work?

A marketplace is a JSON catalog that lists plugins and where to fetch them. Besides the public directory, OpenAI's developer guide on building plugins describes local and Git-based marketplaces for testing and team sharing.

The ChatGPT desktop app reads marketplace files from three places:

To track a marketplace from Git or a folder, use the CLI:

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
codex plugin marketplace list
codex plugin marketplace upgrade
codex plugin marketplace remove marketplace-name

Sources can be GitHub shorthand, HTTPS or SSH Git URLs, or local folders. --ref pins a Git ref, and --sparse limits a Git checkout to one path. list prints every marketplace Codex is considering and the root path it resolves from.

The developer guide says ChatGPT installs plugins into ~/.codex/plugins/cache/$MARKETPLACE_NAME/$PLUGIN_NAME/$VERSION/ and loads that copy rather than reading the marketplace entry directly. For local plugins the version folder is local.

Workspace admins can also import and sync a GitHub marketplace for their team, and can publish a plugin to selected roles in their ChatGPT workspace. Publishing to a workspace does not make a plugin public.

How do you enable or disable a plugin per project?

The plugin browser saves your personal on and off choices in ~/.codex/config.toml. For a repository, set the state in the project's .codex/config.toml. The key is the plugin name, an @, and the marketplace's top-level name:

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

Set enabled = false to switch a plugin off for that project without uninstalling it. Codex loads project config only for trusted projects, and project settings override user and system defaults. These settings do not change plugins that an admin imported through workspace plugin management. Our Codex config guide explains how the config layers stack.

How do you build your own Codex plugin?

OpenAI documents two routes: let a skill scaffold it, or create the folder by hand.

The fast route. Codex ships a built-in $plugin-creator skill (it is @plugin-creator in ChatGPT Work mode). Describe the plugin you want and it scaffolds a .codex-plugin/plugin.json manifest, which the guide calls a compatibility layout. It can also add optional skills/, .mcp.json, hooks/ and assets/ folders and a personal marketplace entry so you can test it right away.

The manual route. A minimal portable plugin is a plugin.json at its root plus a skills/ folder:

my-first-plugin/
├── plugin.json
└── skills/
    └── hello/
        └── SKILL.md

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

Use a stable name in kebab-case; hosts use it as the plugin ID and namespace. Skills are discovered from the root skills/ folder, so the manifest needs no skills field. Each skill is a normal SKILL.md with name and description frontmatter. If you need help writing one, see how to write a SKILL.md.

Optional parts go next to the manifest:

• mcp.json for bundled MCP servers. The guide warns not to just rename a scaffolded .mcp.json, because the portable format needs a transport type for each server.
• hooks/hooks.json for lifecycle hooks. The guide says lifecycle hooks are supported for plugins installed manually in Codex desktop, and plugins with hooks are not eligible for the public directory.
• assets/ for icons, logos and screenshots.
• extensions.com.openai inside plugin.json for OpenAI-specific display details, app mappings and hook paths.

To test, add the plugin to a marketplace. For a repo, copy it to $REPO_ROOT/plugins/my-plugin and add an entry to .agents/plugins/marketplace.json:

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

Paths in source.path are relative to the marketplace root, start with ./, and must stay inside that root. Entries can also point at Git (url or git-subdir) or npm sources. After a change, update the plugin folder and restart the app. The openai/plugins repository has complete public examples, such as Figma and Notion.

When a plugin is ready for the public directory, OpenAI's submission guide covers review. A plugin can include MCP connections, skills or both; remote MCP servers are submitted with a stable, public HTTPS endpoint, and plugins that run a local MCP server follow a separate desktop-only flow.

Should you use a plugin or a plain skill?

If all you need is a set of instructions Codex follows, a plain skill folder is simpler: drop it in .agents/skills and you are done. Reach for a plugin when you want to ship several skills together, add MCP tools that need authentication, or let a team install and update the bundle from a marketplace.

The same split exists in Claude Code, where plugins also bundle skills and MCP servers. Our Claude Code plugins guide covers that side.

Where do the skills inside your plugins live?

Skills are the part of a plugin you edit most, and they are easy to scatter across repos. Kipt keeps prompts and Agent Skills as Markdown in a private GitHub repo you own, and installs every skill into Claude Code or Codex with one command, npx skills add https://github.com/<you>/<repo>.git --all -g. That gives you one source to copy from when you package a plugin. To draft a skill from an existing prompt, the free SKILL.md generator runs in the browser.