Codex Agent Plugins & Catalog Federation (v0.147.0): The Practical Guide
On 7 August 2026 OpenAI shipped Codex CLI v0.147.0. Most coverage flattened it to a single bullet ("plugins now, cool"). The real release changes four things at once, and three of them silently break scripts you probably have in CI today: portable Agent Plugins replace ad-hoc skill installs and merge across a four-tier catalog; a new --approve-for-me flag reads like "auto-approve everything" but doesn't; the old --full-auto shortcut is removed; and Codex now offers opt-in MCP 2026-07-28 with non-blocking server startup. Each has a gotcha worth knowing before you upgrade.
This page is the practical field guide for a reader who already understands Claude Code Skills, subagents, and MCP — and just wants to know what Codex's version really does, where it differs, and what to change in a Monday-morning workflow.
- Know exactly what shipped in Codex CLI v0.146.1 (5 Aug) and v0.147.0 (7 Aug), and why the two together matter
- Understand the four-tier plugin catalog — local, personal, workspace, remote — and the merge/dedup rules that decide which plugin actually wins
- Read `--approve-for-me` correctly: it is a review pass, not a sandbox bypass; the OS-level sandbox stays on
- Migrate off the removed `--full-auto` flag before your next CI run silently fails
- Decide when to opt in to MCP 2026-07-28 in Codex — and what non-blocking server startup buys you
The two-release picture: 0.146.1 then 0.147.0
The August drop is really two releases 48 hours apart, and reading them as one confuses what changed.
- A quiet point release, but it changed the *starting posture* for models tagged cyber-capable (the same class that includes GPT-5.6-Cyber). Auto-approval defaults tighten: network, credential reads and process management now require explicit whitelisting instead of leaning on the older permissive baseline. Codex also began explaining permission changes in the terminal — you see *why* a request was blocked, not just that it was.
- The headline release. Plugins become installable and searchable across a four-tier catalog. A new `--approve-for-me` flag routes approvals through an automatic review pass instead of prompting the human. The old `--full-auto` shortcut is *removed* — a breaking change most CI scripts will hit. And you can now opt in to MCP 2026-07-28, which unlocks paginated discovery, multi-round requests and non-blocking server startup.
- As of 13 Aug 2026 Codex is publishing 0.148.0-alpha builds (alpha.4 through alpha.12 in one week). If you install `latest`, you may land on an alpha; pin to `rust-v0.147.0` for stability until 0.148.0 goes GA.
Portable Agent Plugins: what changed at the file level
Codex has had Skills — a folder of SKILL.md + siblings that any conformant agent can load — for the whole of 2026. v0.147.0 adds a package layer on top: Agent Plugins. A plugin is a distributable unit that can bundle one or more skills, MCP servers, prompts, and configuration into a single artifact you install by name from a catalog. Skills stay portable across agents; plugins are Codex's own packaging and distribution layer.
The important shift is how they're discovered. Before v0.147.0, you copied a skill directory into your project or personal folder by hand. After v0.147.0, Codex looks in four places and merges the results.
The four-tier catalog — and the merge rule that decides who wins
Codex searches four catalogs in a fixed precedence order. When two catalogs contain a plugin with the same name, the higher-precedence one wins and the lower-precedence copy is hidden.
| Tier | Location | Who owns it | Typical use |
|---|---|---|---|
| 1. Local | .codex/plugins/ inside the repo | Committed to the project | Repo-specific tooling; travels with the branch |
| 2. Personal | ~/.codex/plugins/ | Just you, on your machine | Your own hand-rolled or experimental plugins |
| 3. Workspace | Team-shared workspace scope | Your team | Shared conventions, review flows, deploy scripts |
| 4. Remote | Marketplace roots you configure | Vendors + community | Public plugins from marketplace.openai.com or internal registries |
Merge rule: results are deduplicated by plugin name, and the highest-precedence copy is surfaced first. A terraform-drift plugin committed at .codex/plugins/terraform-drift/ in your repo silently shadows the remote-catalog version of the same name. This is by design — repos should be able to freeze a known-good version — but it is the number one source of "why is my plugin behaving differently than the docs say?" on upgrade.
:::tip Read codex plugin list before you debug behavior
codex plugin list shows installed plugins with the source tier each was resolved from. If a plugin is doing something surprising, this is the first command to run — the version you're using may not be the version you think you're using.
:::
Configuring catalogs — the minimal config.toml
Marketplace endpoints and auto-update behavior are set in Codex's config.toml. The v0.147.0 default keeps auto_update = false, which is the right choice for reproducibility but means you have to run updates deliberately.
# ~/.codex/config.toml
[plugins]
enabled = true
marketplace_roots = [
"https://plugins.internal.example.com",
"https://marketplace.openai.com"
]
auto_update = false
update_check_interval_hours = 24
The catalog entry limit was raised from 512 to 2,048 in v0.147.0 — a small number that matters if you point Codex at a large internal registry. Below 512, plugins past the cap were silently truncated from search results; enterprise teams hit this often enough that OpenAI lifted the ceiling.
Working with plugins — the everyday commands
Browse the merged catalog in an interactive picker
/plugins
Search all four tiers at once
codex plugin marketplace search "terraform"
Install the highest-precedence match by name
codex plugin install terraform-drift
See what's installed AND which tier each came from
codex plugin list
Update every installed plugin (opt-in — auto_update defaults off)
codex plugin update
Three security hardenings inside plugin install
The plugin install path in v0.147.0 quietly tightened three things — all worth knowing because they change what "install works" means.
- If a plugin package contains a symlink, Codex skips the symlink instead of following it. This blocks a whole class of path-traversal attacks — a malicious plugin can no longer link `plugin/config` → `/etc/passwd`. The trade-off: legitimate packages that used symlinks for shared assets need to inline them.
- The plugin's declared permissions are validated at install time; a mismatch (declared: read-only; actual: opens sockets) denies network egress rather than warning. This makes least-privilege the default for install-time posture, not a runtime opt-in.
- If two plugins register a tool with the same name, install fails loudly. Before v0.147.0 the second registration silently shadowed the first — a supply-chain footgun where a look-alike plugin could replace a real tool. Now you have to rename or uninstall.
--approve-for-me: what it actually does (and doesn't)
The name reads like "auto-approve every request." That is not what the flag does. --approve-for-me routes approval requests through an automatic review pass that adjudicates each request against your active sandbox mode and approval-policy configuration. If policy says "yes, this is inside the whitelist," the request proceeds without a prompt. If policy says "no or unclear," the request is refused — you are just not asked in the middle of a run.
Two things that stay true:
- The OS-level sandbox is still enforced. On Linux via Bubblewrap; on macOS via the platform sandbox.
--approve-for-mecannot escape the sandbox; it can only decide whether to auto-answer prompts inside it. - Cyber-capable models get the safer defaults from v0.146.1 automatically. Network access, credential reads and process management stay refused unless explicitly whitelisted, no matter what
--approve-for-mesays.
The right mental model: --approve-for-me turns your policy file into the human. If your policy is loose, this flag is dangerous; if your policy is tight, this flag is the missing piece for unattended runs.
Interactive run — policy adjudicates approvals, sandbox stays on
codex --approve-for-me --sandbox workspace-write "refactor auth and run tests"
Exec (non-interactive) run with a structured output contract
codex exec --approve-for-me --sandbox workspace-write \
--output-schema '{"type":"object","properties":{"passed":{"type":"boolean"}}}' \
"run the full test suite"A minimal approval policy that pairs sensibly with the flag:
# ~/.codex/config.toml
[approval_policy]
sandbox_mode = "workspace-write"
[approval_policy.network]
allowed = ["api.github.com", "registry.npmjs.org"]
Everything not on that allow-list is refused — including by --approve-for-me.
The silent breaking change: --full-auto is removed
If you have CI or Makefiles calling codex exec --full-auto, they break on v0.147.0. The flag is gone. The replacement is explicit:
# Before v0.147.0 (broken now)
codex exec --full-auto "run tests"
# v0.147.0 syntax
codex exec --sandbox workspace-write "run tests"
The two are not identical: --full-auto combined a sandbox choice and an approval-policy choice. The new form requires you to state the sandbox explicitly, and if you want the "don't prompt me" half back, add --approve-for-me. This is worth grepping for before you upgrade a shared runner.
MCP 2026-07-28 in Codex — three things you actually get
Codex made the new MCP spec opt-in in v0.147.0. Turn it on when a server you rely on has migrated; leave it off otherwise. Three concrete wins if you flip the switch:
- Paginated discovery. Servers that expose 200+ tools no longer force a giant one-shot list; the client pages through them. Latency to first tool becomes much lower.
- Multi-round requests. A single logical operation can span several client↔server rounds — think an interactive form, a two-step confirm, or a resource read that returns a follow-up token. Before 2026-07-28 this had to be shoehorned into one payload.
- Non-blocking server startup. Codex no longer blocks its own boot on slow MCP servers. A server that takes 4 seconds to warm up used to freeze the whole CLI; now Codex starts, and the server is marked ready when it is.
How this maps onto Claude Code, in one table
If your instinct is Claude, this is the translation table for the same concepts.
| Concept | Codex CLI (v0.147.0) | Claude Code |
|---|---|---|
| Portable instruction unit | Skill (SKILL.md folder) | Skill (SKILL.md folder) — same open standard |
| Packaging / distribution | Agent Plugin (bundles skills, MCPs, config) | Plugin marketplace + skill install |
| Discovery scope | Four-tier catalog (local → personal → workspace → remote) | Project + user + marketplace |
| Auto-approve inside sandbox | --approve-for-me + approval_policy | Permissions in ~/.claude/settings.json |
| Sandbox enforcement | Bubblewrap (Linux) / macOS sandbox | Sandbox with credential masking |
| Long-running MCP servers | Non-blocking startup (MCP 2026-07-28) | Blocking startup unless you opt in |
| "Instructions in the repo" | .codex/plugins/, AGENTS.md | .claude/, CLAUDE.md |
The single biggest practical difference: Codex's four-tier catalog with in-repo .codex/plugins/ shadowing is more aggressive than Claude Code's default. That is a feature — a repo can pin a plugin version and be sure everyone runs it — but it means "upgraded my plugin and nothing changed" is often "your repo pinned an older copy."
A migration checklist for teams already on Codex
- This is the most common cause of a green CI going red after `codex --version` jumps.
- Run `codex plugin list` on a fresh checkout and confirm each source tier matches expectations.
- Rename one plugin's tool, or uninstall the loser.
- Enterprise registries with more than 512 entries were previously truncated silently; now up to 2,048 are visible.
- The upside is paginated discovery and non-blocking startup; the requirement is that the *server* implements the spec.
- Loose policy + this flag = a headless agent doing whatever it wants inside the sandbox.
When Codex plugins beat Claude subagents — and when they don't
Codex plugins are strongest when the unit of reuse is a workflow package — a review flow, a deploy sequence, a Terraform-drift sweep — that you want to ship as one artifact across a whole team, with versioning and a marketplace behind it. The four-tier catalog is genuinely useful in orgs that need "the reviewer plugin the platform team ships, unless my repo overrides."
Claude Code's subagent-plus-skill model is stronger when the unit of reuse is a role ("code-reviewer", "debugger") that composes freely inside a single interactive session, and when you want the same file to run in ChatGPT, Cursor, Gemini CLI and Codex without re-packaging. Skills stay the more portable primitive; plugins are the more powerful distribution layer.
The practical answer for most teams in August 2026 is both: keep skills as the file-level primitive so they travel across agents, and wrap them in a Codex Agent Plugin when you need the marketplace, the catalog federation and the pinning.
Check yourself
0/4Sources & further reading
- openai/codex — GitHub releases (
rust-v0.146.1, 5 Aug 2026 ·rust-v0.147.0, 7 Aug 2026 · ongoing0.148.0-alpha.*) - openai/codex PR #36373 — Add an
--approve-for-meCLI flag (merged 2026-07-31) - ChatGPT & Codex changelog — learn.chatgpt.com/docs/changelog
- Codex CLI v0.147.0 deep-dive — codex.danielvaughan.com (10 Aug 2026)
- Codex updates — August 2026, Releasebot
- Related: SKILL.md — the cross-agent open standard · Coding agent CLIs compared · GPT-5.6-Cyber & Daybreak Red