Claude Code plugins: marketplaces, installing from GitHub, and Codex too
What a plugin is beside a skill or an MCP server, what one can carry, how marketplaces work, the install commands on a server, where it all lives, and that Codex installs from the same marketplace file.
A Claude Code plugin is “a directory of skills, agents, hooks, MCP servers, or other components that Claude Code installs and loads as one unit.” A skill on its own is a folder with a SKILL.md that you drop into ~/.claude/skills/; an MCP server on its own is a line you add with claude mcp add; a plugin bundles any of those so that one command installs someone else’s whole setup, with updates from its marketplace. Plugins come from marketplaces, which are repositories holding a .claude-plugin/marketplace.json that lists plugins and where to fetch each one. On any machine with Claude Code, two commands do it: claude plugin marketplace add owner/repo then claude plugin install name@marketplace. Codex has plugins too, with its own two commands, and OpenAI’s desktop app reads a Claude marketplace file as well as its own; in our test the Codex CLI did the same, so one repository holding skills served both agents. Before installing one, remember what the docs say: “what the plugin runs, it runs as you.”
A plugin, a skill, an MCP server
Anthropic keeps the three apart, and the distinction is where each lives and how it arrives. “Skills, subagents, hooks, and MCP servers all work on their own, without a plugin. A skill you save in ~/.claude/skills/, for example, is available in every project on your machine.” A plugin is for the case where you want “several skills, subagents, hooks, or MCP servers packaged as one unit”: install it “to get a setup someone else built, with one command and updates from its marketplace.” Where a skill loads depends on where it sits, from the skills page:
| Where the skill is | Where it loads |
|---|---|
~/.claude/skills/<name>/SKILL.md | All your projects on this machine, but not Cowork or cloud sessions |
.claude/skills/<name>/SKILL.md in a repository | Sessions in that repository |
skills/<name>/SKILL.md inside a plugin | Wherever the plugin is enabled, as /plugin-name:skill-name |
An MCP server a plugin carries is declared “in .mcp.json at the plugin root, in the same shape as a project .mcp.json,” and runs while the plugin is enabled, under the name plugin:<plugin>:<server>; a server you add yourself with claude mcp add is your own configuration and stays whether or not any plugin is on (how a remote one with an API key is added). One cost worth knowing before you enable several: “An enabled plugin is part of every session, not only the sessions where you use it.”
What a plugin can carry
The manifest reference lays out a plugin as a directory: an optional manifest at .claude-plugin/plugin.json with the name, a version and a description; skills/ (the older commands/ still loads, “prefer skills/ for new plugins”); agents/ for subagent definitions; hooks/hooks.json, and a hooks module, which makes the plugin a “mod”; .mcp.json and .lsp.json for MCP and language servers; bin/, whose files “are on the Bash tool’s PATH while the plugin is enabled”; output styles, workflows, themes and monitors; and a settings.json of which only two keys take effect. A CLAUDE.md at the plugin root “isn’t loaded as context.” The smallest plugin is a skill folder with a manifest added to it, which “loads as a plugin named <name>@skills-dir.”
Marketplaces
“A plugin marketplace is a directory or repository with a .claude-plugin/marketplace.json file that lists your plugins and where to fetch each one.” The file “requires a name, an owner, and a plugins array,” and each entry “needs a name and a source.” A source is a relative path inside the same repository (it must start with ./), a GitHub repository in owner/repo form with an optional branch, tag or commit, any git repository by URL, one subdirectory of a git repository, an npm package, a zip archive over HTTPS, or a command. “The install id is the entry’s name, an @, and the marketplace name.”
Anthropic publishes three general-purpose marketplaces, official, community and demo, and topic-specific ones such as anthropics/skills and anthropics/knowledge-work-plugins. The official one, claude-plugins-official, is added “the first time you start an interactive terminal session, unless a managed policy blocks it,” and “most of what it lists comes from partners and other authors rather than from Anthropic,” which maintains a smaller set of its own such as commit-commands, code-review and the language server plugins; its catalogue is browsable at claude.com/marketplace/plugins, a website rather than a marketplace you add. The names are protected: “Claude Code accepts the official and community names only for marketplaces sourced from github.com/anthropics/ repositories, so a third-party marketplace can’t present itself as an Anthropic one.”
Installing one on a server
From a shell, on a machine you reach over SSH as much as on a laptop:
claude plugin marketplace add owner/repo
claude plugin install my-plugin@marketplace-nameThe first command takes a GitHub repository, a git repository by URL (an https address on a host other than github.com or gitlab.com is fetched as a marketplace.json file unless it ends in .git), a local directory or a hosted file, with #ref to pin a branch or tag; a relative path must start with ./ or ../ because “Claude Code reads a bare name/name as a GitHub repository.” The second installs at user scope by default, so the plugin is on in every project on that machine; --scope project writes the entry into the repository’s .claude/settings.json instead, which “turns the plugin on for your collaborators but doesn’t download it to their machines, so each collaborator also runs” the install once. Inside a session, /plugin opens a panel that does the same with a review step first. Three things about a headless machine: in a claude -p run /plugin “isn’t available in this environment,” though installed plugins load, so the shell commands are the way; “on a machine where no one has opened an interactive Claude Code session yet, the official marketplace isn’t registered,” so a setup script that installs from it adds anthropics/claude-plugins-official first; and a plugin whose marketplace entry runs a command to install it asks before running it, so a script passes --yes.
The rest of the lifecycle. Updates come from the marketplace, but not by themselves for a marketplace you added by owner/repo: auto-update is on for the official marketplace and for marketplaces added through claude.ai, and off for the rest, the community one and two of Anthropic’s own topic lists (knowledge-work-plugins, first-party-plugins) included, so for yours you run claude plugin update <plugin>, whose new version “loads in your next session, or after you run /reload-plugins,” and “there’s no command that updates every plugin at once.” enable and disable switch one off without removing it; uninstall removes it from one scope; claude plugin validate <path> checks a manifest or a marketplace file and exits “with a code a CI job can act on.” Removing a marketplace from the last scope that declares it “also deletes its cache and uninstalls every plugin you installed from it.” Downloaded plugins land under ~/.claude/plugins (a cache per marketplace, plugin and version, plus installed_plugins.json and known_marketplaces.json), a plugin added from a local path loads in place, and which plugins are enabled is recorded in the settings files; “there is one known_marketplaces.json per user, so a marketplace you add in one project is available in every project.”
What you are trusting
The security page is blunt: “A Claude Code plugin you install can execute arbitrary code on your machine with your user privileges,” and “Claude Code’s permission rules and sandbox cover the tool calls Claude makes, not the code a plugin runs by itself.” The install dialog says: “Anthropic does not control what MCP servers, files, or other software are included in plugins and cannot verify that they will work as intended or that they won’t change,” and the marketplaces page adds that “Anthropic doesn’t review third-party marketplaces.” Installing a plugin also enables it unless its manifest says otherwise, so the reading comes before claude plugin install: clone the repository and run claude --plugin-dir <directory> plugin details <name>, which reads the files without starting a session, then open hooks/hooks.json (the command each hook runs), .mcp.json (each server’s command or URL), every file in bin/, and any monitors, which are background commands started with the session, or a mod, which is JavaScript run inside Claude Code with your permissions. A changed config directory is no container: the code still runs as you. And a tag on the marketplace pins the catalogue, not the plugin: an entry fetched from its own repository moves with its branch unless the entry pins a commit, and a plugin from a marketplace with auto-update on can change on disk after you read it.
Codex installs from the same repository
Codex has plugins too, and they are not experimental: OpenAI’s plugins page says they “can include skills and MCP servers,” browser extensions and hooks, and that “Codex CLI also has a plugin browser” while “the IDE extension doesn’t support plugins.” The commands are close to Anthropic’s, with their own spelling:
codex plugin marketplace add owner/repo
codex plugin add my-plugin@marketplace-nameA pin is owner/repo@ref or --ref; there is no enable, disable or update subcommand, the browser’s space bar turns an installed plugin on or off, and codex plugin marketplace upgrade refreshes a marketplace. Then “start a new session before using its bundled skills or tools.” Codex’s own marketplace file is .agents/plugins/marketplace.json, in a repository or as a personal list in your home folder, and its portable plugin format puts a plugin.json at the plugin root with skills/ and an mcp.json beside it. Installed plugins go under ~/.codex/plugins/cache/ (or wherever CODEX_HOME points) and the browser’s choices into ~/.codex/config.toml. A plugin’s hooks are not trusted on install: “Codex skips them until the user reviews and trusts the current hook definition.”
The useful part for anyone running both agents: Codex reads Claude’s marketplace file. OpenAI’s build page lists “a legacy-compatible marketplace at $REPO_ROOT/.claude-plugin/marketplace.json” among what the desktop app reads, and says of manifests that “OpenAI also accepts legacy and Claude-compatible manifests, but new packages should use this format.” The CLI’s own documentation doesn’t mention the Claude file, but its source has looked for it since 0.122.0 in April 2026, and at the current release (0.161.0) it checks .agents/plugins/marketplace.json first and .claude-plugin/marketplace.json after, and for a plugin manifest a portable plugin.json, then .codex-plugin/plugin.json, then .claude-plugin/plugin.json. We tried it on October 5, 2026, with Claude Code 2.1.289 and Codex 0.160.0: a GitHub repository holding the Claude marketplace file and two skill folders, its one entry pointing at the repository root (source: "./", no plugin manifest, a skills list naming one folder), installed with the two commands on each agent, and each agent then saw that one skill and not the other (Codex names it plugin:skill). What carries across is the skills: OpenAI’s plugin parts are skills, MCP servers, browser extensions and hooks, so a Claude plugin’s agents, commands, output styles, LSP servers and monitors have no Codex equivalent (its submission guide says to turn commands and agents into skills), and “Claude marketplace listings and approvals don’t transfer” to OpenAI’s own catalogue. Two documented alternatives to the shared repository: Codex’s /import brings instructions, settings, skills and plugins across from a Claude Code setup on the same machine, and a skill folder can simply be copied into ~/.agents/skills/ for Codex or ~/.claude/skills/ for Claude Code.
How new this is
Claude Code’s plugin system shipped in 2.0.12 on October 9, 2025, with marketplaces, /plugin install and /plugin validate from the start; branch and tag pins came in 2.0.28, subdirectory sources in 2.1.69. Codex added a plugin system in CLI 0.110.0 on March 5, 2026, the plugin browser in 0.117.0 that month, the marketplace commands over April and May, with the Claude marketplace file read from 0.122.0 on, the portable manifest in 0.146.0 at the end of July and installing portable plugins in 0.147.0 in August. Both catalogues change often, which is the reason the commands above name a marketplace rather than a plugin.