Codex can now install plugins from local, Git-backed, and remote marketplace sources, which makes plugin review a supply-chain decision.
That is the boring sentence.
It is also the sentence that can save a team from a very annoying Friday.
The moment agent tooling becomes installable from GitHub, the question is no longer just, “does this plugin help?”
The better question is, “what exactly am I letting into my development runtime?”
That sounds dramatic.
It is not.
It is the same mental model developers already use for npm packages, GitHub Actions, VS Code extensions, shell scripts, and CI templates.
Plugins are useful because they package capabilities.
Capabilities are useful because they can touch workflows.
Workflows are sensitive because they often sit next to source code, credentials, local files, build logs, and issue context.
So this is not a panic post.
It is a checklist.
Use it before adding a Codex plugin marketplace from GitHub.
Use it before pressing install on a remote catalog plugin.
Use it before telling a whole team, “yeah, just add this marketplace.”
Especially use it when a plugin looks extremely convenient.
Convenience is usually where the bill hides.
The short version
Treat a Codex marketplace as a software supply-chain boundary.
Pin Git-backed marketplaces when possible.
Inspect the plugin before enabling it.
Separate personal experiments from repo-approved tooling.
Treat upgrades as review events, not background tidying.
Know whether the source is local, Git-backed, or remote-only.
Check bundled skills, apps, MCP servers, and auth expectations.
Record what changed when a plugin moves from “interesting” to “installed.”
That is the whole playbook.
The rest of this post explains the practical version.
Why this matters in 2026
Agent tools are moving from prompts to packaged operating environments.
That shift is good.
It means less copy-pasted setup.
It means reusable skills.
It means cleaner team conventions.
It means a plugin can bundle the moving parts that make an agent workflow useful.
But packaging also changes risk.
A prompt is usually visible.
A markdown instruction file is usually reviewable.
A plugin can carry more surface area.
It may include skills.
It may include app integrations.
It may include MCP server definitions.
It may expect authentication.
It may come from a local folder.
It may come from a Git repository.
It may come from a remote catalog.
OpenAI’s Codex documentation describes plugin marketplace sources as local, Git-backed, or remote in different parts of the Codex system.
The CLI can add marketplaces from GitHub shorthand, Git URLs, SSH Git URLs, or local marketplace root directories.
The app server API can list plugin state and source metadata.
For Git-backed entries, that metadata can include a URL, path, ref name, and commit SHA.
For remote catalog entries, the source can be remote-only.
That detail matters.
A Git SHA is reviewable.
A local path is inspectable.
A remote catalog entry requires a different kind of trust.
None of those are automatically bad.
They are simply different trust shapes.
Good teams name the shape before they install the thing.
The mental model
Do not start with the plugin name.
Start with the boundary.
Ask this first:
What source am I adding to Codex?
Then ask:
What can this plugin ask Codex to do?
Then ask:
Who will maintain the source after today?
Then ask:
What happens when it upgrades?
That order is boring on purpose.
Security work is often just refusing to be dazzled in the first five minutes.
Check 1: identify the marketplace source
Codex plugin marketplaces can be added from several source styles.
OpenAI’s CLI documentation says codex plugin marketplace add accepts GitHub shorthand such as owner/repo or owner/repo@ref.
It can also accept HTTP or HTTPS Git URLs.
It can accept SSH Git URLs.
It can accept local marketplace root directories.
That means two installations can look similar in the UI while having different operational risks.
owner/repo is not the same as owner/repo@ref.
A floating branch is not the same as a pinned release.
A local marketplace directory is not the same as a remote source.
A private SSH Git URL is not the same as a public GitHub shorthand.
Before installing, write down the exact source string.
If you cannot explain the source string, do not make it a team default yet.
Use this tiny table.
| Source shape | What to verify | Default posture |
|---|---|---|
| Local marketplace root | Owner, path, repo review | Good for experiments |
| GitHub shorthand | Repository owner, ref, history | Pin before team use |
| HTTPS Git URL | Domain, ref, sparse path | Review like dependency |
| SSH Git URL | Access scope, identity, ref | Review like private dependency |
| Remote catalog | Publisher trust, metadata, policy | Install only after inspection |
The point is not to memorize source types.
The point is to avoid installing “a plugin” when you are really adding “a moving marketplace.”
That small wording change helps.
Check 2: pin the Git ref before team rollout
OpenAI’s docs explicitly support pinning a Git ref with --ref.
They also support GitHub shorthand with an @ref.
That is the line between “I installed what I reviewed” and “I installed whatever this branch means later.”
For a personal scratch workflow, a floating branch can be acceptable.
For a team workflow, it deserves a raised eyebrow.
For a production-adjacent coding agent setup, pin it.
Examples:
codex plugin marketplace add owner/repo --ref v1.2.3
codex plugin marketplace add owner/repo@v1.2.3
codex plugin marketplace add <https://github.com/example/plugins.git> --ref 8f3a1c2
Do not treat main as a version.
main is a conversation.
A tag, release branch, or commit SHA is a stronger review anchor.
If a plugin needs frequent updates, that is fine.
But the update should be deliberate.
The person upgrading should know what changed.
The team should know what changed.
The rollback should be obvious.
Pinned refs are not glamorous.
They are one of those small practices that quietly prevent chaos.
Check 3: use sparse checkout when the marketplace repo is large
OpenAI’s marketplace command supports repeated --sparse PATH values for Git-backed marketplace repos.
The docs also note that --sparse is valid only for Git marketplace sources.
This matters when a repository contains more than the marketplace files you want.
Maybe the repo includes examples.
Maybe it includes build scripts.
Maybe it includes unrelated experiments.
Maybe it includes a whole monorepo.
If only one path is needed, narrow the checkout.
Example:
codex plugin marketplace add <https://github.com/example/plugins.git> --sparse .agents/plugins
Sparse checkout is not a complete security boundary.
Do not oversell it.
It is still useful operational hygiene.
It reduces what lands locally.
It makes review smaller.
It makes accidental coupling less likely.
It makes the next person less likely to ask, “why is this giant repo here?”
That last benefit is underrated.
Future you is also a stakeholder.
Future you is tired.
Help future you.
Check 4: inspect before enabling
The Codex CLI plugin browser groups plugins by marketplace.
The docs say you can switch marketplace tabs, open a plugin to inspect details, and press Space on an installed plugin to toggle its enabled state.
That inspection step is not ceremonial.
It is the actual control point.
Before enabling, check the plugin name.
Check the marketplace it came from.
Check the description.
Check bundled skills.
Check bundled apps.
Check bundled MCP server names if shown.
Check whether it implies authentication.
Check whether it changes the way Codex can interact with files, browsers, apps, or external services.
Most plugin risk is not “evil code.”
Most plugin risk is “a capability appeared in the workflow and nobody noticed.”
That is how teams drift.
One person adds a useful tool.
Another person assumes it is approved.
A third person uses it in a sensitive repo.
Nobody was malicious.
The system still got looser.
Inspection is where you slow that down.
Check 5: separate personal and repo marketplaces
OpenAI’s plugin build docs distinguish between repository marketplaces and personal marketplaces.
For a repo marketplace, the docs point to $REPO_ROOT/.agents/plugins/marketplace.json.
They describe storing plugins under $REPO_ROOT/plugins/.
For a personal marketplace, the docs point to ~/.agents/plugins/marketplace.json.
They describe storing plugins under ~/.codex/plugins/.
That distinction is extremely useful.
Personal marketplaces are for personal experiments.
Repo marketplaces are for team intent.
Do not blur the two casually.
If a plugin is only for your local workflow, keep it personal.
If a plugin is part of how a repository should be worked on, put it through repository review.
That review can be lightweight.
It still needs to exist.
Use repo marketplaces when the plugin belongs to the project.
Use personal marketplaces when the plugin belongs to your desk.
The desk is allowed to be weird.
The repo should be boring.
Boring is a compliment here.
Check 6: understand path resolution
OpenAI’s build docs state that Codex resolves source.path relative to the marketplace root.
It is not relative to .agents/plugins/.
That sounds like a tiny detail.
It is exactly the kind of tiny detail that creates broken installs.
It can also create misleading reviews.
When reviewing a marketplace file, do not only read the path string.
Resolve it from the marketplace root.
Confirm the plugin directory it actually points to.
Confirm that the files you reviewed are the files Codex will read.
If the marketplace is Git-backed, pair that with the pinned ref or SHA.
If the marketplace is local, pair it with the absolute local path during review.
If the marketplace is repo-local, pair it with the repository commit.
This is tedious.
It is also the difference between “I reviewed a file” and “I reviewed the installed thing.”
Those are not always the same.
Check 7: treat upgrade as a change-management event
The CLI supports refreshing configured marketplaces with codex plugin marketplace upgrade.
It can refresh all configured Git marketplaces.
It can also refresh one marketplace by name.
That is convenient.
It is also where accidental supply-chain drift can enter.
Do not run upgrades as an invisible habit in a team workflow.
Before upgrading, capture the current source.
Capture the ref name.
Capture the SHA when available.
Run the upgrade.
Inspect what changed.
Test the plugin in a non-sensitive workspace.
Then promote it to the normal workflow.
For small teams, this can be a short note in a changelog.
For larger teams, it may belong in a pull request.
Either way, make the change visible.
Agent tooling changes the behavior of the worker sitting next to your code.
That deserves at least as much ceremony as updating a CI action.
Not a parade.
Just a receipt.
Check 8: use app-server metadata when building internal tooling
OpenAI’s Codex app server API exposes plugin-related endpoints.
The API overview includes marketplace/add.
It includes plugin/list.
It includes plugin/read.
It includes plugin/install.
It includes plugin/uninstall.
The same overview says plugin summaries include a source union.
Local plugins return a local source with a path.
Git-backed marketplace entries can return URL, path, ref name, and SHA.
Remote catalog entries return a remote source.
For remote-only catalog entries, the docs note that callers should use remoteMarketplaceName instead of marketplacePath when reading or installing.
That is more than implementation trivia.
It means internal tools can show reviewers the source shape.
They can flag unpinned Git marketplaces.
They can display SHAs.
They can detect remote-only entries.
They can surface install and auth policy metadata.
They can list bundled skills, apps, and MCP server names when available.
If you are building a team dashboard for Codex plugins, start there.
Do not invent a separate inventory format first.
Use the metadata Codex already exposes.
Then add team policy on top.
Good internal tooling should make the safe path boring.
That is the whole trick.
Check 9: review bundled MCP servers carefully
MCP servers are powerful because they connect agents to tools and data.
That same power makes them worth reviewing.
If a plugin bundles or configures MCP servers, treat that as a separate checklist item.
Ask what the server can read.
Ask what the server can write.
Ask whether it can execute commands.
Ask whether it talks to external networks.
Ask whether it requires OAuth.
Ask whether it can access private documents.
Ask whether it can access secrets indirectly through local files or environment variables.
Ask whether the server is active only in specific workspaces.
Ask whether the server has a clear uninstall path.
This is not because MCP is bad.
MCP is useful precisely because it gives agents reach.
Reach needs boundaries.
The more useful the plugin, the more likely this section matters.
Convenient plugins often come with convenient reach.
Convenient reach is still reach.
Name it.
Check 10: check authentication policy before first use
Some plugins may be harmless until authentication enters the picture.
That is when the security shape changes.
A plugin that reads public docs is one thing.
A plugin that can access a company’s issue tracker is another.
A plugin that can act through a browser connector is another again.
Before installing, ask whether the plugin needs auth.
Before enabling, ask which account will authenticate.
Before team rollout, ask whether that account has the right scope.
Avoid authenticating with a personal admin account because it is faster.
That sentence should not need to be written.
It always needs to be written.
Use a least-privilege account when possible.
Use workspace-scoped credentials when possible.
Document who owns the token.
Document how to revoke it.
Document what breaks if it is revoked.
The revocation plan is not pessimism.
It is maintenance.
Maintenance is where security becomes real.
Check 11: test in a boring workspace first
Do not test a new plugin for the first time inside your most sensitive repo.
Create a small workspace.
Use fake files.
Use a fake issue.
Use fake docs.
Use a toy branch.
Run the plugin there.
Watch what it asks for.
Watch what tools it exposes.
Watch what files it touches.
Watch whether it behaves differently after auth.
Watch whether it keeps state.
Then decide if it belongs in the real workflow.
This can take ten minutes.
Ten minutes is cheap compared with explaining an unexpected repo change.
The small workspace is not just for security.
It is for usability.
Some plugins are safe but noisy.
Some plugins are clever but overbuilt.
Some plugins solve a problem you do not have.
Testing exposes that too.
Check 12: keep a rollback path
The CLI docs include marketplace removal.
The app server API includes plugin uninstall.
That means rollback should be part of the install note.
Before team rollout, write the undo command.
Write which marketplace name to remove.
Write which plugin to uninstall.
Write the previous pinned ref if you are upgrading.
Write which local files were changed.
Write whether Codex needs restart after local install changes.
OpenAI’s build docs note that after changing a plugin or local install, restarting Codex makes the changes get picked up.
That matters in rollback too.
If a plugin is disabled but the runtime still feels odd, restart before assuming the rollback failed.
The rollback note can be tiny.
It just needs to exist before trouble starts.
Trouble is a poor documentation environment.
Nobody writes elegant runbooks while annoyed.
A practical install checklist
Use this before adding a marketplace.
-
I know whether the source is local, Git-backed, or remote.
-
I know the exact marketplace source string.
-
I know who maintains the source.
-
I know whether the source is pinned.
-
I know whether a sparse checkout should be used.
-
I know which plugin I am actually installing.
-
I inspected the plugin details before enabling.
-
I checked bundled skills.
-
I checked bundled apps.
-
I checked bundled MCP server names.
-
I checked whether authentication is required.
-
I checked whether the plugin introduces external network access.
-
I checked whether it can read local files.
-
I checked whether it can write local files.
-
I checked whether it can run commands.
-
I tested it in a small workspace.
-
I know how to uninstall it.
-
I know how to remove the marketplace.
-
I know whether Codex needs restart after local changes.
-
I recorded the review result somewhere the team can find.
If that feels too heavy, use a two-tier rule.
Personal experiment: source, plugin, auth, uninstall.
Team rollout: source, pin, metadata, capabilities, auth, test, rollback, owner.
That is usually enough.
A simple policy for teams
Here is a policy that is intentionally plain.
Personal plugins stay personal.
Repo plugins require review.
Git-backed marketplaces should be pinned.
Floating branches require an explicit reason.
Remote-only catalog plugins require source and publisher review.
Plugins that bundle MCP servers require capability review.
Plugins that require auth require owner and revocation notes.
Upgrades require a visible change note.
Uninstall instructions must be documented before rollout.
This policy is not fancy.
That is why it might actually get used.
The best plugin policy is the one a developer can remember while shipping something under deadline.
Security policy that only works in a workshop is theater.
Security policy that fits in a pull request template is useful.
Pull request template for repo-approved plugins
Copy the shape, not necessarily the exact words.
## Codex plugin review
- Marketplace source:
- Source type: local / Git-backed / remote
- Pinned ref or SHA:
- Sparse paths:
- Plugin name:
- Bundled skills:
- Bundled apps:
- Bundled MCP servers:
- Auth required:
- File access expectations:
- Network access expectations:
- Test workspace result:
- Rollback command:
- Owner:
This is intentionally boring.
It turns a plugin install into a reviewable artifact.
That is the goal.
You are not trying to create paperwork.
You are trying to leave enough trace that the next person understands the decision.
When not to install the plugin yet
Pause if the marketplace source is unclear.
Pause if the repository owner is unclear.
Pause if the plugin cannot be inspected.
Pause if the Git source is floating and nobody can explain why.
Pause if the plugin asks for broad auth but only solves a narrow task.
Pause if it bundles an MCP server nobody reviewed.
Pause if the uninstall path is unknown.
Pause if it only works with someone’s personal account.
Pause if the plugin replaces a small shell command with a large opaque workflow.
Pause if the pitch is mostly vibes.
Vibes are not evidence.
They are seasoning.
Do not build access policy out of seasoning.
When installation is reasonable
Install if the source is clear.
Install if the marketplace is pinned or intentionally local.
Install if the plugin solves a recurring workflow.
Install if the capability surface is understandable.
Install if auth scope matches the job.
Install if the team knows who owns it.
Install if rollback is simple.
Install if the plugin reduces repeated manual setup without hiding critical decisions.
Install if it makes Codex more consistent across the team.
That last one is the upside.
Plugins can make agent workflows less chaotic.
They can turn “everyone has their own magical folder” into a shared tool contract.
They can make onboarding easier.
They can reduce prompt drift.
They can make a team’s Codex setup feel like a product instead of a pile of notes.
That is worth doing.
Just do it with a review loop.
The GitHub-specific angle
GitHub makes installation feel familiar.
That is both good and dangerous.
Developers already trust owner/repo patterns.
They already know stars, releases, issues, and commit history.
They already know how to skim a README.
But GitHub familiarity can create a shortcut in the brain.
A plugin marketplace is not just a README.
It is not just a code sample.
It is a source Codex may browse and install from.
So check the usual GitHub signals.
Check recent commits.
Check release tags.
Check maintainers.
Check issues.
Check whether the plugin docs match the actual files.
Check whether marketplace paths are narrow.
Check whether examples ask for suspicious credentials.
Check whether install instructions recommend a pinned ref.
Then check the Codex-specific signals.
Check marketplace source.
Check source type.
Check plugin metadata.
Check bundled capabilities.
Check auth policy.
Check runtime behavior.
The GitHub review tells you whether the source looks healthy.
The Codex review tells you what you are adding to the agent runtime.
You need both.
What I would do by default
For my own workstation, I would allow local experiments.
I would keep them out of repo config until they prove useful.
For a team repo, I would require pinned Git-backed marketplaces.
I would prefer a repo marketplace for approved plugins.
I would keep the marketplace file reviewable in Git.
I would add a short plugin review note to pull requests.
I would test upgrades in a sample workspace.
I would avoid installing remote-only plugins into sensitive workflows until the team has a clear source and policy story.
I would pay special attention to MCP servers and auth.
I would not block plugins just because they are new.
That would be lazy in the other direction.
The goal is not to freeze the toolchain.
The goal is to make the toolchain legible.
Legible systems can improve.
Opaque systems can only surprise you.
Surprises are fun at birthdays.
They are less fun in development infrastructure.
Related reading
FAQ
Are Codex plugins unsafe?
No.
That is the wrong starting point.
Plugins are a packaging mechanism.
Packaging can be safe or unsafe depending on source, permissions, auth, review, and update behavior.
The practical move is to review the boundary before installing.
Is a Git-backed marketplace better than a remote catalog?
Not automatically.
A Git-backed marketplace can be easier to pin and inspect.
A remote catalog may still be appropriate if the publisher and policy model are clear.
The important thing is to know which trust model you are using.
Should every marketplace be pinned?
For team workflows, pinning should be the default.
There can be exceptions.
The exception should be written down.
If nobody can explain why a marketplace floats, it probably should not float.
Does sparse checkout make a plugin safe?
No.
Sparse checkout narrows what is checked out from a Git-backed marketplace repo.
It helps review and reduces local clutter.
It is not a substitute for source review, capability review, auth review, or testing.
What is the biggest mistake teams make?
Treating plugin installation as a UI preference.
It is closer to adding a dependency, an IDE extension, and a workflow integration at the same time.
That does not mean it should be slow.
It means it should be visible.
What should a small team do first?
Start with a simple rule.
Personal experiments stay personal.
Repo-approved plugins go through a short review note.
Git-backed team marketplaces are pinned.
Upgrades are recorded.
That alone removes a lot of accidental drift.
Sources
- OpenAI Codex plugins documentation
- OpenAI Codex plugin build documentation
- OpenAI Codex CLI reference for plugin marketplaces
- OpenAI Codex app server API overview
Final thought
Codex plugins are exciting because they can make agent workflows portable.
That is the good part.
The catch is that portability moves trust around.
When a marketplace comes from GitHub, a local folder, or a remote catalog, you are choosing where that trust begins.
So make the choice visible.
Pin what should not drift.
Inspect what will run.
Separate experiments from team defaults.
Treat upgrades like changes.
Keep rollback boring.
That is not anti-plugin.
That is how plugins become usable infrastructure instead of another mystery layer in the stack.