Claude Code vs Codex Plugins — Native Agent Packages

Native Claude Code plugins and Codex plugins are not ordinary editor extensions. They are packages for agent behavior: manifests, skills, commands, hooks, MCP servers, app connectors, and UI metadata that change what the coding agent can see and do.

Last verified: 2026-06-27. Local CLI versions used for verification: Claude Code 2.1.185, Codex CLI 0.141.0. The inspected shell exposes codex, not a separate cdex binary; this guide treats cdex CLI as shorthand unless a specific wrapper is provided.

If you only use this for five minutes

Before installing a native agent plugin, do this:

1. Open the plugin manifest: .claude-plugin/plugin.json or .codex-plugin/plugin.json.
2. Follow every path it references: skills, commands, agents, MCP servers, app descriptors, hooks, and executables.
3. Separate instructions from authority. A skill tells the model how to work; an MCP server, hook, executable, or app connector changes what the agent can touch.
4. Check provenance: local folder, pinned Git ref, marketplace entry, remote bundle, or floating source.
5. Decide what you would allow manually. If you would not give a human contractor access to that email, ticket system, repo, or shell command, do not give it to the plugin by accident.

The fast win is not memorizing both ecosystems. It is learning to spot the trust boundary: where prompt text stops and tool authority begins.

Quick reference

The useful mental model: plugins are becoming installable operating procedures for coding agents. Some teach the agent how to work. Some attach the agent to external systems. The serious ones do both.

The capability stack

Read native plugins as a stack, not as a single feature. Each layer answers a different question: where did this package come from, what does it teach, what does it connect, and what authority does it create?

flowchart TD
  User["User task"] --> Runtime["Coding agent runtime"]
  Rules["Project rules and tests"] --> Runtime
  Market["Marketplace or Git source"] --> Manifest["Plugin manifest"]
  Manifest --> Instruction["Skills, commands, agents"]
  Manifest --> Capability["MCP, apps, hooks, executables"]
  Instruction --> Runtime
  Capability --> Runtime
  Runtime --> Work["Code, reviews, docs, tickets"]
  Capability --> Boundary["Trust boundary: auth, writes, egress"]

Marketplace/Git source → plugin manifest
                         ├─ skills, commands, agents → coding agent runtime
User task + project rules ───────────────────────────→ coding agent runtime → work
                         └─ MCP, apps, hooks, executables → trust boundary

That diagram is the whole article in one picture. Claude Code is strongest in the instruction lane: commands, agents, hooks, and procedural skills. Codex is strongest in the capability lane: app connectors, remote bundles, MCP routing, UI metadata, and runtime loading. Both systems can cross into the other lane.

What a native agent plugin really is

A classic editor extension extends the editor. A native agent plugin extends the agent’s behavior surface.

That difference matters. A Claude Code or Codex plugin can ship Markdown instructions, but it can also add tools, workflow entry points, lifecycle hooks, app metadata, authentication prompts, and remote MCP endpoints. Installing one can change the agent’s habits, not just its menu.

The old question was: “What does this extension add to VS Code?” The better question now is: “What new authority does this agent package create?”

A plugin may do one or more of these jobs:

This is why “plugin” is slightly misleading. The better term is agent package.

The shape of real plugin inventories

The source-backed inventories make the product difference more concrete. The inspected Claude official marketplace snapshot listed 240 marketplace entries. Only the locally materialized payloads can be component-counted without fetching every external repository, but that local slice already shows Claude’s workflow bias: commands, agents, skills, hooks, and MCP declarations are first-class package contents.

The inspected OpenAI curated Codex snapshot listed 180 plugins. Its manifest fields point the other way: 154 plugins declared app descriptors, 72 declared skills, and 8 declared MCP server files. That does not make Codex “only apps,” but it explains why the UI feels like an integration catalog first and a workflow library second.

flowchart LR
  subgraph Claude["Claude official marketplace snapshot"]
    CMarket["240 entries"] --> CLocal["51 local payloads
component-scanned"]
    CLocal --> CWorkflow["78 workflow pieces
28 commands + 23 agents + 27 skills"]
    CLocal --> CAuthority["20 authority pieces
15 MCP files + 5 hooks"]
  end
  subgraph Codex["OpenAI curated Codex snapshot"]
    OMarket["180 plugins"] --> OApps["154 app descriptors"]
    OMarket --> OSkills["72 skill roots"]
    OMarket --> OMcp["8 MCP files"]
  end
  CWorkflow --> Lesson["Review the package
by authority surface"]
  CAuthority --> Lesson
  OApps --> Lesson
  OSkills --> Lesson
  OMcp --> Lesson

Claude official snapshot
  240 marketplace entries
    └─ 51 local payloads scanned
         ├─ 78 workflow pieces  = commands + agents + skills
         └─ 20 authority pieces = MCP files + hooks

OpenAI curated Codex snapshot
  180 plugins
    ├─ 154 app descriptors
    ├─ 72 skill roots
    └─ 8 MCP files

The caveat matters: marketplace rows and component payloads are different evidence. A marketplace can have hundreds of rows while only some payloads are locally inspectable. A runtime review must follow the row to the actual installed payload before judging risk.

How Claude Code plugins are wired

Claude Code’s public plugin docs and official plugin repository describe a package layout built around .claude-plugin/ metadata plus component folders. A typical plugin can contain a manifest, MCP configuration, commands, agents, skills, and a README. The public CLI confirms this is a package manager surface, not just a file convention: claude plugin exposes install, list, enable, disable, marketplace, update, validate, and uninstall commands.

The important files are:

A marketplace entry can point at a local plugin folder or a remote Git source pinned by ref and SHA. That is good for reproducibility, but it also means the review target is the plugin payload, not only the marketplace row.

Claude example: feature-dev

The official feature-dev plugin is the cleanest example of Claude’s center of gravity. It is not just a command named “build a feature.” It encodes a development process.

The command requires the agent to:

1. explore the codebase;
2. understand existing patterns;
3. ask clarifying questions;
4. present architecture options;
5. wait for approval;
6. implement;
7. review and summarize.

That is a deliberate brake against the common agent failure mode: start coding while the problem is still fuzzy. Installing the plugin changes the workflow Claude follows before code appears.

Claude example: code-review

The official code-review command is more obviously multi-agent. The public plugin page and command file describe independent reviewers, confidence scoring, filtering, and GitHub comment output. In the inspected source, this is not a vague “review my PR” prompt. It is a review protocol with reviewer roles and a scoring threshold.

The key point is not the exact reviewer count. The point is that Claude plugins can package orchestration. They can define which agents participate, what each agent looks for, how findings are scored, and how output is posted.

Claude example: ralph-loop

ralph-loop is the operationally interesting one because it uses a hook-like loop around the session. Instead of adding one more prompt template, it changes what happens when the session would otherwise stop. The plugin pattern is closer to a local control-plane extension than to a static prompt pack.

That makes the trust boundary much sharper. A workflow plugin can affect when commands run, when sessions continue, and what gets re-fed into the model.

How Codex plugins are wired

Codex exposes both a local CLI and UI/app surfaces. The inspected CLI is codex, and codex app --help shows app-server and remote-control subcommands alongside the interactive CLI. Plugin management lives under codex plugin.

Codex’s open-source Rust code gives a clearer view of loader mechanics than Claude’s public plugin repos do. The plugin runtime reads manifests, materializes plugin sources, caches installed content, enables plugins through config, and then loads capabilities into the agent runtime.

The important files are:

The verified CLI surface is smaller than Claude’s:

codex plugin add
codex plugin list
codex plugin marketplace
codex plugin remove

That does not mean the internals are simpler. The Rust source has separate modules for marketplace parsing, source materialization, plugin store/cache management, manifest parsing, loader composition, remote bundles, remote installed-plugin sync, app/MCP routing, and config overlays.

The UI-to-runtime path

The visual trick is to stop treating the plugin browser as the plugin. In Codex, the UI is a discovery and install surface. The runtime still has to resolve a source, materialize a payload, parse a manifest, and inject capabilities into the model context.

flowchart TD
  subgraph Discovery["Discovery surfaces"]
    App["Codex app\nPlugins directory"]
    Cli["Codex CLI\n/plugins"]
    Local["Local marketplace\n.agents/plugins"]
  end
  App --> Catalog["Catalog entry"]
  Cli --> Catalog
  Local --> Catalog
  Catalog --> Source["Source policy\nremote, shared, local, Git"]
  Source --> Install["Installed copy\ncache and config"]
  Install --> Manifest[".codex-plugin/plugin.json"]
  Manifest --> Skills["Skills"]
  Manifest --> Apps["App connectors"]
  Manifest --> Mcp["MCP servers"]
  Manifest --> Hooks["Hooks"]
  Skills --> Context["Model-visible\nplugin guidance"]
  Apps --> Context
  Mcp --> Context
  Hooks --> Runtime["Lifecycle behavior"]
  Context --> Runtime["Agent runtime"]

Codex app / CLI / local marketplace
        ↓
Catalog entry → source policy → installed cache/config → plugin manifest
                                                ├─ skills → model context
                                                ├─ apps   → model context
                                                ├─ MCP    → model context
                                                └─ hooks  → lifecycle behavior

That is the boundary that matters for debugging. If a plugin is visible in the browser but not in the runtime, inspect the source, cache, enablement, manifest, auth, and capability injection layers before rewriting prompts.

The Codex loader path

The Codex path is useful because it is visible in source.

At a high level, install and load look like this:

1. resolve a plugin from a configured marketplace;
2. materialize the source, either local or Git;
3. copy the plugin into a cache keyed by marketplace and plugin identity;
4. enable the plugin in config;
5. parse .codex-plugin/plugin.json;
6. load skills;
7. load MCP servers;
8. load apps;
9. load hooks;
10. render capability summaries and plugin guidance into the agent runtime.

The model is not supposed to “call a plugin” directly. The loaded plugin contributes capabilities: skills, MCP tools, app tools, hooks, and context. That matters when debugging. If a Codex plugin appears to do nothing, the failure might be marketplace resolution, cache install, config enablement, manifest parsing, auth state, MCP composition, app routing, or model-visible capability injection.

Codex example: linear

The official curated linear plugin is the compact example. Its manifest declares:

{
  "name": "linear",
  "version": "0.0.3",
  "description": "Find and reference issues and projects.",
  "skills": "./skills/",
  "apps": "./.app.json",
  "mcpServers": "./.mcp.json",
  "interface": {
    "displayName": "Linear",
    "category": "Productivity",
    "defaultPrompt": [
      "Triage or update relevant issues for this task with clear next actions"
    ]
  }
}

That shape says a lot. The plugin is not only a Linear prompt. It has skills, app metadata, and an MCP declaration. The UI can present it as “Linear,” the runtime can attach an app connector, and the agent can read Linear-specific skills before using the tool.

The inspected OpenAI curated snapshot contained 180 plugins. In that snapshot, 154 declared app descriptors, 72 declared skills, and 8 declared MCP server files. That is why Codex plugins feel app-heavy: the official set is mostly about attaching product integrations to the agent runtime.

Marketplace compatibility is already leaking through

The most surprising source detail is in Codex marketplace discovery. Codex looks for its native marketplace files, but the inspected source also recognizes Claude’s marketplace path:

const MARKETPLACE_MANIFEST_RELATIVE_PATHS: &[&str] = &[
    ".agents/plugins/marketplace.json",
    ".agents/plugins/api_marketplace.json",
    ".claude-plugin/marketplace.json",
];

That does not mean Claude plugins run in Codex automatically. It means the marketplace shape is close enough that Codex deliberately knows about the Claude-style catalog location.

The easy mappings are mostly metadata and skills:

The hard mappings are runtime semantics:

A mostly-procedural Claude skill can probably be ported with light edits. A workflow plugin like feature-dev needs design work. A Codex app plugin like linear cannot be converted into a Claude plugin unless the app connector story becomes MCP-only or Claude gets an equivalent app-auth layer.

Claude Code vs Codex UI: the product difference

Claude’s strongest public examples say: “teach the coding agent a better way to work.”

Codex’s strongest official snapshot says: “make the coding agent aware of external products and app-backed capabilities.”

That is an oversimplification, but it is a useful one.

Claude Code plugins lean into local development workflow: commands, agents, hooks, skills, MCP, and process control. The official examples feel like disciplined work modes: review this PR with multiple reviewers; build this feature in phases; keep looping until the task is finished.

Codex plugins lean into runtime composition and product surfaces: interface metadata, app connector IDs, MCP routing, marketplace policy, remote bundles, and config overlays. The official curated set starts with things like Linear, Atlassian, Google Calendar, Gmail, Slack, Teams, SharePoint, Outlook, Canva, and Figma. Those are product integrations before they are coding workflows.

There is overlap. Claude knowledge-work plugins also use MCP and role/team skills. Codex has methodology plugins and skill-heavy community packs. But the center of gravity is different enough that it should affect how plugins are reviewed.

Security review checklist

Do not install an agent plugin as if it were a harmless prompt file. Review it like a small software dependency with access to an agent session.

Before installing, answer these questions:

For Claude, pay special attention to hooks, executables, MCP, and command tool permissions. For Codex, pay special attention to app connector auth, remote bundle provenance, MCP/app routing, and config overlays.

Trust-boundary ladder

Not every plugin file has the same risk. Review from lowest authority to highest authority, then stop at the first layer you would not approve manually.

flowchart TD
  Readme["README and display metadata
Explains intent"] --> Skill["Skills
Influence model behavior"]
  Skill --> Command["Commands and agents
Shape workflows and delegation"]
  Command --> Mcp["MCP servers
Expose tools and data egress"]
  Mcp --> App["App connectors
Attach account data and auth"]
  App --> Hook["Hooks and executables
Run around the session"]
  Hook --> Update["Update channel
Changes future installed behavior"]

metadata < skills < commands/agents < MCP < app auth < hooks/executables < update channel

The ladder is intentionally conservative. A Markdown skill can still mislead the model, but an app connector, MCP server, hook, executable, or floating update source can change what the agent can touch.

How to inspect a plugin quickly

Start with the manifest, then follow every referenced path. Do not stop after reading the README.

For Claude Code:

# Replace PLUGIN_DIR with the plugin root.
find PLUGIN_DIR -maxdepth 3 -type f \
  \( -path '*/.claude-plugin/*' -o -path '*/commands/*' -o -path '*/agents/*' -o -path '*/skills/*' -o -name '.mcp.json' \) \
  -print

Read these in order:

1. .claude-plugin/plugin.json;
2. marketplace row that points to the plugin;
3. .mcp.json;
4. commands/*.md;
5. agents/*.md;
6. every SKILL.md;
7. hook and executable references.

For Codex:

# Replace PLUGIN_DIR with the plugin root.
find PLUGIN_DIR -maxdepth 4 -type f \
  \( -path '*/.codex-plugin/*' -o -name '.app.json' -o -name '.mcp.json' -o -path '*/skills/*' -o -name 'hooks.json' \) \
  -print

Read these in order:

1. .codex-plugin/plugin.json;
2. marketplace row and install/auth policy;
3. .app.json;
4. .mcp.json;
5. skills/**/SKILL.md;
6. hooks files;
7. remote bundle or Git source metadata.

A short inspection is enough to catch the biggest category mistake: thinking a plugin is “just prompts” when it actually installs tools or lifecycle behavior.

When to use which system

Use Claude Code plugins when the main need is a disciplined local workflow: code review protocol, feature development flow, design critique, refactor rules, or loop control. Claude’s plugin model is strong when behavior is mostly inside the coding session.

Use Codex plugins when the main need is app-backed capability: issue trackers, docs, email, calendar, design tools, analytics, deployment systems, or product integrations that the UI can present and authenticate. Codex’s plugin model is strong when the agent needs a product connector plus skills around it.

Use either system for plain skills. Markdown skills are the most portable part of both ecosystems. If a plugin is mostly a SKILL.md, porting is realistic. If it depends on slash-command semantics, hook payloads, app IDs, or auth policy, treat the port as a redesign.

Common failure modes

The debugging pattern is simple: inspect marketplace, manifest, install/cache state, config enablement, component paths, auth state, and then model-visible capability context. Do not debug the prompt first if the loader never attached the capability.

Background knowledge that unlocks the next articles

This guide becomes more useful once these pieces are familiar:

Those terms also create a good follow-up map:

What this means for agentic coding

The next wave of coding-agent reuse is not going to look like copying one magic prompt. It will look like package management.

Project rules still matter. CLAUDE.md, AGENTS.md, tests, and review gates are still the source of truth for a repo. Native plugins sit one layer above that. They package repeatable procedures and connectors so the agent can enter a project with better defaults.

That power cuts both ways. A good plugin can make the agent slower in exactly the right way: inspect first, ask questions, check assumptions, then write code. A bad plugin can silently widen the tool boundary or normalize a workflow nobody reviewed.

The practical rule: install skills generously, install tools carefully, and install hooks only after reading the code.

Sources

• Anthropic, Claude Code plugins
• Anthropic, Claude Code plugin marketplaces
• OpenAI, Codex CLI
• OpenAI, Codex plugins
• OpenAI, openai/codex source

See also

• Setting Up Claude Code for a New Project
• Prompt Patterns
• Researching Codebases with AI Agents
• Reviewing AI-Generated Code
• Writing an Effective CLAUDE.md