Codex CLI Plugins Reference

Updated September 30, 2026 by Alex Sorokoletov

Independent reference, not affiliated with OpenAI. Tables are generated from the Codex CLI source at rust-v0.159.2 (v0.159.2). Official documentation: learn.chatgpt.com.

A Codex CLI plugin is a folder with a manifest that bundles skills, MCP servers, apps and hooks, installed from a marketplace with codex plugin add <plugin>@<marketplace>. Codex reads its own .codex-plugin/plugin.json, the Agent Plugins plugin.json, and Claude Code and Cursor manifests, so those plugin folders load without a Codex-specific file.

What is a Codex plugin?#

A plugin is the unit Codex installs, enables and removes as one piece. Its manifest points at the components it ships; any component key left out falls back to a conventional path inside the plugin folder, so a folder with only skills/ and .mcp.json needs no paths in the manifest at all.

Every path in the manifest must start with ./, stay inside the plugin root and contain no ..; a path that breaks these rules is skipped with a warning rather than failing the whole plugin. hooks uses the same format as a standalone hooks.json (see the hooks reference), either as a file or inline. Keys not listed above are not read.

{
  "name": "review-kit",
  "version": "1.2.0",
  "description": "Code review skills and a linter MCP server",
  "skills": "./skills",
  "mcpServers": "./.mcp.json",
  "hooks": "./hooks/hooks.json",
  "interface": {
    "displayName": "Review Kit",
    "category": "Coding",
    "defaultPrompt": ["Review the staged diff"]
  }
}

interface holds the listing shown in plugin pickers. defaultPrompt accepts at most 3 prompts of up to 128 characters each; extra or longer entries are dropped with a warning.

Where does Codex look for the plugin manifest?#

Codex checks these paths in order and uses the first manifest it finds:

A root plugin.json counts only when its $schema names the Agent Plugins 1.0.0 schema, so an unrelated plugin.json in a repository is never mistaken for a plugin. When a root Agent Plugins manifest exists, a .codex-plugin/plugin.json next to it is read as a Codex-specific overlay.

How do I install a Codex plugin from a marketplace or GitHub?#

Add a marketplace, then install plugins from it by name. A marketplace source is a local path, owner/repo[@ref], an HTTPS Git URL or an SSH Git URL; --sparse PATH checks out only part of a large repository.

codex plugin marketplace add owner/repo --ref main
codex plugin list --marketplace my-market
codex plugin add review-kit@my-market
codex plugin remove review-kit@my-market

A marketplace is a repository or folder with a marketplace file at one of these paths. Codex also reads a marketplace file at the same relative paths under your home directory.

Each plugin entry in a marketplace file has a name and a source, which is either a relative path string or an object with one of these source kinds:

How do I enable, disable or configure an installed plugin?#

Installed plugins are keyed by <plugin>@<marketplace> in config.toml. enabled = false turns a plugin off without uninstalling it. mcp_servers overlays policy on the MCP servers the plugin ships: the manifest owns how a server is launched, while config.toml owns whether it starts, its auth and which tools it exposes.

[plugins."review-kit@my-market"]
enabled = true

[plugins."review-kit@my-market".mcp_servers.linter]
enabled_tools = ["lint_file"]
default_tools_approval_mode = "prompt"

Codex records each added marketplace under [marketplaces.<name>] so codex plugin marketplace upgrade can refresh it:

Plugin support is a stable feature and on by default:

Plugins vs skills vs MCP servers#

A skill is one folder with a SKILL.md that teaches the agent a task. An MCP server exposes tools over the Model Context Protocol and can be configured directly under [mcp_servers] in config.toml (see the config reference). A plugin is the distribution layer above both: a versioned folder, installed from a marketplace, that can carry several skills, MCP servers, app connectors and hooks and is switched on or off as one entry. Use a bare skill or MCP server for something personal; package a plugin when a team should install the same set with one command.

Can I use Claude Code plugins in Codex?#

Codex reads .claude-plugin/plugin.json manifests and .claude-plugin/marketplace.json marketplace files, so a Claude Code plugin repository can be added with codex plugin marketplace add directly. Hook commands receive both Codex and Claude Code variable names for the plugin folder and its data directory:

Markdown commands listed in a manifest are converted into skills when the plugin is installed. Plugin hooks are not managed hooks, so they go through the same "Hooks need review" prompt as hooks in your own config before they run.

Frequently asked questions#

What is a Codex plugin?#

A Codex plugin is a folder with a plugin.json manifest that packages skills, MCP servers, app connectors and lifecycle hooks so they install, update and switch off together. Plugins come from marketplaces, which are Git repositories or local folders with a marketplace.json. Missing manifest keys fall back to ./skills, ./.mcp.json, ./.app.json and ./hooks/hooks.json inside the plugin folder.

What is the difference between Codex plugins and skills?#

A skill is a single SKILL.md folder describing one task. A plugin is a distributable bundle that can contain many skills plus MCP servers, app connectors and hooks, and it is installed from a marketplace and enabled or disabled as one [plugins."name@marketplace"] entry. Skills inside a plugin load from its skills/ directory or the paths its manifest lists.

How do I install a Codex plugin from GitHub?#

Run codex plugin marketplace add owner/repo (add --ref for a branch or tag, --sparse for a subdirectory), then codex plugin list to see what it offers and codex plugin add <plugin>@<marketplace> to install one. The repository needs a marketplace file such as .agents/plugins/marketplace.json or .claude-plugin/marketplace.json.

Can I use Claude Code plugins in Codex?#

Yes, for the parts Codex supports. Codex reads .claude-plugin/plugin.json and .claude-plugin/marketplace.json, loads skills, MCP servers and hooks from them, converts Markdown commands into skills at install, and sets CLAUDE_PLUGIN_ROOT and CLAUDE_PLUGIN_DATA for hook commands. Manifest keys outside Codex's field list are not read.

Can a Codex plugin bundle hooks and MCP servers?#

Yes. hooks in the manifest points at a hooks file, lists several, or embeds the hooks inline, and ./hooks/hooks.json is used when the key is absent. mcpServers points at a JSON file or holds an inline object of servers, defaulting to ./.mcp.json. Plugin hooks still need approval in the "Hooks need review" prompt.

Where does Codex store installed plugins?#

Installed plugins are cached under $CODEX_HOME/plugins/cache, which is ~/.codex/plugins/cache unless CODEX_HOME is set. The per-plugin settings live in config.toml under [plugins."<plugin>@<marketplace>"], and each added marketplace is recorded under [marketplaces.<name>] with its source, ref and last revision. codex plugin remove uninstalls a plugin and deletes its cache.

How do I disable a Codex plugin without uninstalling it?#

Set enabled = false under its entry in config.toml, for example [plugins."review-kit@my-market"]. To keep the plugin but stop one of its MCP servers, set enabled = false under [plugins."review-kit@my-market".mcp_servers.<server>] instead. Setting plugins = false under [features] turns off plugin support entirely.

Release-by-release changes: Codex CLI version tracker. All Codex CLI pages: Codex CLI reference index.