How to Use ECC with OpenAI Codex: Skills, Agents, AGENTS.md and Plugin Setup
How to Use ECC with OpenAI Codex: Skills, Agents, AGENTS.md and Plugin Setup
Quick Answer
Yes. Everything Claude Code (ECC) supports OpenAI Codex through a native plugin path. Register ECC’s plugin marketplace, install the ECC plugin, then verify with codex plugin list --json. ECC skills, rules, MCP and file-based memory map onto Codex skills, AGENTS.md instructions, MCP config and the plugin manifest. The key caveat: this is feature mapping, not feature parity. Claude Code-native behaviors such as lifecycle hooks and subagents do not transfer 1:1.
Quick Install
The current Codex plugin flow has three steps. Do not skip the middle one: registering a marketplace does not install a plugin.
# 1. Make the ECC marketplace known to Codex (register only)codex plugin marketplace add affaan-m/ECC
# 2. Install the ECC plugin from that marketplace (this is the actual install)codex plugin add ecc@ecc
# 3. Verify the plugin is installed and loadedcodex plugin list --json
After installing, start a new Codex session (or reload the current one) so the plugin’s components are loaded, then confirm that ECC-provided skills and instruction assets are visible.
Command surface note: Codex plugin commands evolve between CLI releases. If a flag or identifier in this post differs from what your CLI accepts, treat
codex plugin --help,codex plugin list --json, and the current OpenAI Codex plugin documentation as authoritative.
Does ECC Work with Codex?
ECC is a community project that centralizes the rules, skills, agents, MCP servers, security guardrails and memory you would otherwise configure per agent. Its README and cross-harness architecture documentation describe Codex as a supported cross-harness target, delivered through the native Codex plugin mechanism rather than through a Claude Code adapter.
Support level matters, so read it precisely:
- “Supported” here means ECC ships a plugin that Codex can install and load through the official plugin interface.
- It does not mean Codex behaves like Claude Code. The two harnesses expose different native mechanisms.
- Avoid the phrase “first-class harness” unless the ECC repository itself uses that wording; in practice the docs describe a plugin path that is maintained and recommended, which is strong enough.
The single most important framing of this article is: feature mapping, not feature parity. Every ECC capability below is translated onto whatever Codex mechanism is the closest real match, and the degree of equivalence varies by capability.
Install ECC in Codex
Prerequisites
- Codex CLI installed and authenticated (
codex --versionandcodex login). - A project directory you are comfortable letting the plugin load instructions into.
Understand the four states
People get confused because they treat marketplace registration and plugin installation as one action. They are separate states, and each needs its own verification:
| State | What it means | How to confirm |
|---|---|---|
| Marketplace registered | Codex knows where ECC’s plugin catalog lives. Nothing is installed yet. | codex plugin marketplace list |
| Plugin installed | The ECC plugin package has been pulled from the marketplace. | codex plugin list --json |
| Plugin enabled / loaded | A session actually loads the plugin’s components. | Plugin appears as enabled/loaded in codex plugin list --json; or start a new session and observe the plugin’s instructions taking effect |
| Components visible | Skills, commands and instruction assets exposed by the plugin are usable. | Inspect the plugin’s declared contents; try a plugin-provided skill/command in a fresh session |
If a plugin is installed but you do not see its components, the usual cause is a stale session, not a broken install: restart the session first, then re-check.
Step-by-step install
# Register the ECC marketplacecodex plugin marketplace add affaan-m/ECC
# Confirm the marketplace is registered (and note the marketplace short name)codex plugin marketplace list
# Install the ECC plugin from that marketplace# Identifier format: <plugin>@<marketplace>. Confirm the exact identifier# from your marketplace listing if "ecc@ecc" does not resolve.codex plugin add ecc@ecc
# Verify installation statecodex plugin list --jsonThen start a fresh Codex session and verify behavior, not just package state: ask Codex to list what project/plugin instructions it is following, and try one of the skills ECC exports.
Trust and security
ECC is a third-party community plugin. Before you add it, skim the repository so you know what the plugin declares (skills, instructions, MCP servers, commands). After install, keep Codex’s approval mode and sandbox settings at a level you are comfortable with. A plugin’s instructions and commands run inside your session’s existing permission model; they do not bypass approvals, and installing a plugin does not grant it rights beyond what your Codex configuration allows.
Current Plugin Path vs Legacy Sync
There are two historical ways to get ECC assets into Codex, and only one of them is the recommended install path.
Current path: the plugin
The plugin flow (marketplace add → plugin add → verify) is the maintained, recommended route. Plugin behavior is managed by Codex’s plugin loader: install, list, enable/disable, and update through the CLI.
Legacy path: the sync script
Older ECC documentation and scripts synchronized asset files directly into your project or home configuration: copying skill files, instruction text, MCP config entries, and AGENTS.md content into place.
Be careful about the status of that script:
- Present (file exists in the repo) does not equal documented, supported, or recommended.
- Treat the sync script as a compatibility/legacy mechanism. It is not the preferred install path, and assuming it “still works” is unsafe because its behavior is not guaranteed or tested against current Codex releases.
- If you previously used the sync script, do not keep re-running it after you move to the plugin — that is exactly how duplicate and stale assets appear.
Repo-local tooling vs end-user tooling
Some commands you will see in the ECC repository are maintainer tooling, not user-facing install steps. For example, npm run harness:audit (and similar npm scripts) only run inside a clone of the ECC repository after npm install, and they audit the repository’s own harness matrix. They are not part of the Codex install flow and are not an end-user verification command. See the “Advanced” section below.
ECC Feature Mapping: Claude Code vs Codex
This table is the heart of the article. Each row states the closest real Codex mechanism and an honest parity rating. Parity ratings are: Full (equivalent native behavior), Partial (works with format or enforcement differences), No (no equivalent), or Harness-dependent (depends on configuration or adapter).
| ECC Capability | Claude Code | Codex Mapping | Parity? | Notes |
|---|---|---|---|---|
| Skills | Claude Code skills (SKILL.md assets) | Codex skills exposed through the plugin manifest / AGENTS.md skill references | Partial | Asset format and invocation differ; skill content is largely portable |
| Rules / instructions | AGENTS.md and CLAUDE.md instruction files | AGENTS.md instructions loaded per Codex instruction scope | Partial | Same file format family, but precedence and discovery scope follow Codex rules |
| Agents | Claude Code subagents (declared agent roles with scoped tools) | Role/prompt-level specialization via instructions and skills; not an identical parallel subagent runtime | No / Partial | Do not assume native multi-agent parity; see the Agents section |
| Hooks | Claude Code lifecycle hooks (pre/post tool, stop, notification, session events) | No Claude-style hook parity; Codex substitutes approvals, sandbox, and tool/command policies | No | ECC hooks become policy/instruction text in Codex, not enforced lifecycle events |
| MCP servers | MCP servers configured for Claude Code | MCP servers configured for Codex (plugin-provided or manual config) | Partial | Server config is portable in principle; permission and approval handling differ |
| Memory / knowledge | ECC file-based knowledge and instincts | File-based knowledge assets; automatic loading depends on the Codex adapter and AGENTS.md references | Harness-dependent | Portable in principle; continuous-learning hooks are Claude-side |
| Security (AgentShield) | Guardrails enforced through hooks and permission prompts | Instruction-based guardrails plus your approval/sandbox settings | Partial / No | Instruction text is advisory; not hook-enforced blocking |
Keep this table conservative. Where a mapping is uncertain, prefer “Partial” or “Harness-dependent” over an enthusiastic “Full.”
AGENTS.md and ECC
What AGENTS.md actually does in Codex
In Codex, AGENTS.md files supply instructions that Codex reads and follows when working in a directory. Discovery is scoped: a global AGENTS.md (user-level), a project-root AGENTS.md, and nested AGENTS.md files in subdirectories all participate, each applying to work in its own scope.
Precedence
Instruction precedence in Codex is defined by the current official rules, and the practical summary is:
More specific project-level instructions may override broader or global instructions according to Codex’s current instruction-precedence rules.
Do not oversimplify this to “project wins over global.” The actual outcome can depend on whether an instruction is a hard rule, how specific and recent it is, and where it is declared (nested file, project root, plugin-provided instructions, or a direct user instruction in the session). If you need the exact ordering, consult the current Codex AGENTS.md documentation rather than guessing.
Does the ECC plugin rewrite your AGENTS.md?
No — not necessarily. This is a common misunderstanding, and it matters for migration safety.
- The ECC plugin contributes instruction and skill assets through its plugin manifest. Those assets are loaded as plugin-provided instructions when Codex runs the plugin.
- The plugin does not automatically rewrite the physical
AGENTS.mdin your repository, and it should not be expected to. - It was the legacy sync script that wrote physical files and appended content to AGENTS.md. If you are on the plugin path, there is no file-copying step that touches your project files.
If you want ECC rules to appear as a visible, versioned AGENTS.md in your repo, add references or copies yourself as part of your project setup. Do not assume the plugin does that for you.
ECC Skills in Codex
ECC ships skill assets, and through the Codex plugin path those assets are exposed to Codex. Skills are the closest Codex analog to Claude Code skills: self-contained, purpose-scoped instructions that an agent can load on demand.
Practical notes:
- Skill content (the markdown body, usage guidance, and references) transfers across harnesses well because it is mostly prose and structured steps.
- The envelope differs: Claude Code discovers skills through its skill directory conventions, while Codex discovers plugin-provided skills through the plugin manifest and any AGENTS.md skill references ECC contributes.
- Invocation style may differ. Test one skill in a fresh Codex session instead of assuming identical command names.
ECC Agents / Role Specialization in Codex
Claude Code supports declared subagents: named roles with their own instructions and, in many configurations, scoped tool access and the ability to run delegated work.
Does Codex have the same thing? Not necessarily — and this is where overclaiming hurts.
- Codex may expose role or task specialization primarily through instructions and skills: you give the model a role definition as part of its context and it behaves accordingly.
- A prompt-level role is not the same as a native subagent with independent execution, guaranteed parallelism, or separate tool scopes.
- ECC agent definitions therefore map best to role/prompt-level specialization in Codex rather than to “multi-agent roles.”
If a future Codex release adds native subagents that plugins can register, treat that as a new capability and update the mapping. Until then, describe ECC agents in Codex as specialized role prompts built from skills and instruction assets, and be explicit that execution characteristics follow Codex’s model, not Claude Code’s.
Hooks: Where Parity Breaks
Hooks are the biggest compatibility gap between the two harnesses, and the distinction matters:
- Claude Code has native lifecycle hooks: scripts that run on events such as tool calls, session start/stop, and notifications. ECC uses them for enforcement and automation.
- Codex does not currently provide Claude-style hook execution parity. Saying this is accurate. Saying Codex has “no hooks at all” is too strong, because Codex does have control mechanisms — just different ones.
The correct framing is no Claude-style hook parity, not no hooks:
| Claude Code mechanism | Codex substitute | Parity |
|---|---|---|
| Lifecycle hooks (event-driven scripts) | No direct equivalent | No |
| Pre/post tool enforcement | Approval prompts and tool/command policies | Partial |
| Permission prompts | Codex approval and sandbox modes | Partial |
| MCP access control | MCP permission/allowlist configuration | Partial |
| ECC hook definitions | Policy text and instructions loaded into context | Partial (advisory, not enforced events) |
In practical terms: ECC treats hook definitions as policy text embedded in the instructions Codex loads. That text can steer behavior, but it is advisory. If your workflow depends on deterministic, event-triggered enforcement (for example, a pre-commit-style block before a destructive tool runs), verify that the equivalent Codex approval or sandbox setting actually provides it. Do not assume a Claude Code hook fires the same way in Codex.
MCP and Tool Configuration
ECC bundles or references MCP server configurations. In Codex, MCP servers are configured through Codex’s own MCP configuration (which may be populated by the plugin or set manually), not through Claude Code’s config format.
Two practical cautions:
- Config format differs. Port the server definitions and environment variables, then verify each tool shows up in Codex’s tool list. Do not copy a Claude Code MCP config file verbatim and expect Codex to read it.
- Context cost is real. Every MCP server you attach adds tool definitions to the context window. ECC can make it easy to attach many servers; attach only the ones the current project needs, and watch how much context the loaded tools consume.
Memory / Continuous Learning
ECC stores knowledge in files (notes, instincts, learnings) so that the underlying knowledge is portable across harnesses in principle. But portability of files is not the same as automatic loading or automatic learning.
Be precise about what is and is not true in Codex:
- ECC’s file-based knowledge assets can be read by Codex if they are on disk and if instructions (for example, an AGENTS.md reference or an explicit user instruction) point Codex at them.
- Whether the plugin auto-loads those files depends on the current ECC-for-Codex adapter and on the instruction assets the plugin contributes. Verify it rather than assuming it.
- Automated continuous-learning hooks that run in Claude Code (capturing learnings at session end, promoting instincts) may not fire the same way in Codex, because that behavior in Claude Code is often hook-driven and Codex lacks hook parity.
Safest statement, and the one this article stands behind:
File-based knowledge assets are portable in principle, but the degree of automatic loading and of continuous learning depends on the current Codex adapter and on the instruction assets the plugin contributes.
AgentShield with Codex
ECC’s security layer, AgentShield, packages guardrails that restrict what an agent may do. In Claude Code those guardrails are enforced through hooks and permission prompts. In Codex the same rules travel as instruction-based policy text, and their effectiveness depends on how strongly Codex follows instructions plus the approval and sandbox settings you configure.
The result is a lower enforcement guarantee:
- Claude Code AgentShield: hook-enforced, deterministic blocking in many cases.
- Codex with ECC AgentShield content: guidance that biases the model, backed by Codex approvals/sandbox. Useful, but not equivalent enforcement.
If you use AgentShield for hard security boundaries, keep Codex’s own approval and sandbox mechanisms on and treat ECC’s shield text as a second layer, not the primary enforcement.
Practical ECC + Codex Workflow
A clean daily workflow separates Codex mechanisms from ECC concepts:
- Install once. Register the ECC marketplace, install the plugin, verify with
codex plugin list --json(see Quick Install). - Start a fresh session. Restart Codex after install so plugin components load.
- Confirm instructions. Ask Codex what instructions it is currently following, and confirm the ECC-provided instruction assets are in that set.
- Exercise skills. Run one ECC-provided skill to confirm discovery and invocation work in Codex.
- Attach MCP selectively. Add only the MCP servers the current task needs, then confirm their tools are visible.
- Keep AGENTS.md yours. If ECC guidance belongs in your project permanently, add your own AGENTS.md references or copies. Do not rely on the plugin to write files.
- Verify safety boundaries. Keep approvals/sandbox on; treat ECC security text as advisory on top of Codex’s own controls.
Advanced: ECC Repository Tooling (Not End-User Verification)
You will see commands like this in the ECC repository and in older guides:
npm run harness:audit -- --format jsonClassify this correctly before running it:
- It is repository-local tooling, not an end-user install or verification command.
- It must be run from a clone of the ECC repository, after
npm install, with the repository as the working directory. - It audits the repository’s cross-harness matrix and is aimed at ECC maintainers and contributors.
For a normal Codex user, this command is irrelevant to installing or verifying ECC. The only verification commands you need are Codex’s official plugin interfaces (codex plugin list --json and related codex plugin subcommands).
Migrating from Legacy Sync Safely
If you previously used the legacy sync script and now want to move to the plugin, do it in a way that never risks your own configuration. The sync script may have written or appended content to your AGENTS.md, and your AGENTS.md may also contain your own project instructions mixed in.
Never delete a project AGENTS.md solely because the old sync script touched it.
Follow this order:
- Inventory. List every file the sync script may have written or modified: AGENTS.md files, skill directories, MCP config entries, and any copied assets under your home or project config.
- Diff. Compare current files against your version control history (or a backup) to see exactly what the sync script added.
- Backup. Commit or copy everything before changing anything. A backup is non-negotiable.
- Identify ECC-managed content. Mark the blocks or files that are purely duplicated ECC content versus the parts that are your own instructions.
- Install the plugin (Quick Install) so ECC capabilities arrive through the supported path.
- Validate. Start a fresh Codex session and confirm the plugin’s instructions and skills are active.
- Remove duplicates only. Delete only the ECC-managed copies that the plugin now provides — and only the parts you positively identified as duplicated ECC content. Leave your own project instructions untouched.
If you are unsure whether a section is ECC-managed or yours, leave it in place. The cost of a duplicate is far lower than the cost of deleting your project’s instructions.
Troubleshooting by State
Fix problems by diagnosing the actual state first instead of blindly re-installing everything.
Marketplace missing
Codex does not know ECC’s catalog.
codex plugin marketplace add affaan-m/ECCcodex plugin marketplace list # confirm it now appearsMarketplace exists, plugin missing
The marketplace is registered but the plugin was never installed (or was removed).
codex plugin add ecc@ecc # confirm the exact plugin@marketplace identifiercodex plugin list --json # confirm the plugin now appearsPlugin installed but disabled / not loading
The plugin is on disk but not active in the current session.
- Check its state in
codex plugin list --json. - Enable it with the enable command shown by
codex plugin --help, if your CLI version separates enable from install. - Start a new Codex session — a stale session often does not pick up newly installed plugins.
Plugin installed but components missing
The plugin loads, but skills or instruction assets are not visible.
- Inspect the plugin’s declared contents (via
codex plugin list --jsonand the CLI’s detail subcommands) and compare with what ECC’s release notes say it should export. - Restart the session.
- Verify that ECC’s instruction assets are actually in the instruction set Codex reports it is following.
- Check whether the installed plugin version matches the current ECC release; if not, update the plugin.
If a plugin is installed and enabled but its components still do not appear, that is a plugin-content or version mismatch — reinstalling the marketplace will not fix it.
Should Codex Users Install ECC?
Install ECC if you want a single, centralized source of rules, skills, memory and security guidance that follows you across harnesses, and you are comfortable with the plugin path and with the mapping table above. It is most valuable if you also use Claude Code (or plan to) and want consistent behavior between the two.
Skip it (or install it later) if:
- You need Claude-Code-specific behavior — hooks, subagents, enforcement — in Codex today. Those do not have parity.
- You only use Codex and prefer to configure skills and AGENTS.md yourself with minimal third-party surface.
- You do not want to review and trust a community plugin’s instructions and commands.
The honest recommendation: ECC with Codex is useful for consistency and centralized assets, not for making Codex behave like Claude Code.
FAQ
Is ECC compatible with OpenAI Codex? Yes. ECC supports Codex through a native plugin path (marketplace registration plus plugin install), as documented in the ECC repository. Compatibility means ECC’s plugin loads in Codex and its assets map onto Codex mechanisms — it does not mean feature parity with Claude Code.
What is the difference between codex plugin marketplace add and codex plugin add?
Registering a marketplace only tells Codex where a plugin catalog lives. Installing the plugin (codex plugin add <plugin>@<marketplace>) is the step that actually pulls the plugin. You need both, in that order, plus a fresh session for the plugin to load.
How do I confirm ECC is really installed and enabled?
Run codex plugin list --json and check that the ECC plugin appears in an installed/enabled state, then start a new session and confirm ECC-provided instructions are among the instructions Codex reports it is following, and that an ECC skill is discoverable.
Does ECC reach Codex through AGENTS.md? Partly. ECC’s instruction and skill assets are contributed through the plugin and can surface in the instructions Codex loads. But not everything is AGENTS.md: skills go through the plugin’s skill assets, MCP goes through Codex MCP config, and security/approval behavior goes through Codex’s own controls. The precise role of AGENTS.md follows Codex’s current instruction rules.
Will the ECC plugin modify my repository’s AGENTS.md? No — not necessarily. The plugin contributes assets that Codex loads at runtime; it is not designed to rewrite the physical AGENTS.md in your repo. Physical file writes came from the legacy sync script, which is not the recommended path.
Does Codex support ECC hooks and agents the same way Claude Code does? No. Codex does not provide Claude-style hook parity, and ECC agents map to role/prompt-level specialization rather than identical native subagents. Treat those as the two biggest gaps in the mapping.
Key Takeaways
- Plugin path is current. Register the ECC marketplace, then install the plugin — marketplace registration and plugin installation are two different actions.
- Verify with Codex interfaces.
codex plugin list --jsonand relatedcodex pluginsubcommands are the end-user verification tools; repository npm scripts are maintainer tooling. - Feature mapping, not parity. Skills, rules and memory port reasonably; hooks and subagents do not. Where uncertain, prefer “Partial” over “Full.”
- AGENTS.md is not auto-edited by the plugin. The plugin contributes instructions at runtime; physical file writes were the legacy sync script’s job, and that path is not recommended.
- Migrate safely. Inventory, diff, back up, install the plugin, validate, and only then remove ECC-managed duplicates — never delete a project AGENTS.md just because the old sync script touched it.
FinalWords
ECC is a genuinely useful cross-harness layer, and the Codex plugin path is the right way to consume it: it installs through Codex’s official plugin interface, keeps its assets manageable, and does not write into your project files the way the legacy sync script did. What ECC cannot do is make Codex into Claude Code. Hooks, subagent execution and deterministic security enforcement remain Claude-side strengths, and every Codex mapping in this article should be read through that lens.
Because both ECC and the Codex plugin surface move quickly, treat the command examples here as a starting point: confirm the current syntax with codex plugin --help and the official Codex plugin documentation, and check the ECC repository for the latest release notes and any changes to its Codex support. If you also use Claude Code, see our guide on installing ECC with Claude Code, and remember that the goal is a consistent workflow across harnesses — with honest expectations about where each harness ends.
Final Words + More Resources
My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me
Here are also the most important links from this article along with some further resources that will help you in this scope:
- 👨💻 Everything Claude Code (ECC) Official Repository
- 👨💻 ECC README - Codex Plugin Setup
- 👨💻 ECC Cross-Harness Architecture
- 👨💻 What Is Everything Claude Code (ECC)?
- 👨💻 How to Install ECC with Claude Code
- 👨💻 What Is Everything Claude Code (ECC)? Skills, Agents, Hooks, Memory and Security Explained
Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!
Comments