Codex
Run the same home from OpenAI Codex. What to install, how to wire a home for it, what to trust, and the limits that remain.
A home that works in Claude Code works in OpenAI Codex too. The skills are the same files, and a session ended in one host is in the other's context next time. One thing differs: a Codex plugin cannot carry hooks or an MCP server that knows which home it serves, so those are written into each home's .codex/ folder. This page is the one place that setup is described.
| Launch | codex from the home |
| Skills | $<skill>, for example $sync |
| Manual | AGENTS.md, read natively |
| Hooks and MCP server | Written per home into .codex/ |
| Settings | The home's .claude/settings.json and settings.local.json, turned into .codex/config.toml and .codex/rules/ |
Before you start
- A home that already exists. Create it from Claude Code (Quickstart). A brand-new home created with
$initunder Codex is not exercised yet. - A current Codex. Setup and
upgradestop when a home wired for Codex runs on an older one:
codex --version # needs 0.154.0 or newer
npm install -g @openai/codex@latest # updates an older oneSet it up
Add the plugin to Codex
codex plugin marketplace add AgentLayer1/agentlayer-agent-marketplace
codex plugin add agentlayer@agentlayerRunning the plugin from your own clone? Add the clone's folder as the marketplace and install agentlayer@agentlayer-dev instead.
Wire the home
There are two ways, and you need only one:
- A new home. While
initruns in Claude Code, it asks "Do you also run OpenAI Codex from this home?". Answer Yes, wire it now. - A home you already have. Start
codexfrom the home, trust the folder when asked, and run$upgrade. It wires the home even when there is nothing else to upgrade.
Trust the folder and the hooks
Start codex from the home again:
cd ~/Documents/Agents/Oppi && codexTrust the folder if it asks. Then run /hooks and trust the four entries whose command runs the plugin's src/cli.ts: session-start, session-capture twice, and guard.
Until you do, Codex starts without your agent's context and captures nothing.
From then on a Codex session starts with your agent's context, sessions from either host land in the same brain, and each session block records which host and model produced it.
Updating
Codex installs a copy of the plugin into its own cache, so an update is a remove and an add:
codex plugin remove agentlayer@agentlayer && codex plugin add agentlayer@agentlayerOn a clone of the plugin, swap agentlayer@agentlayer for agentlayer@agentlayer-dev.
Then run $upgrade from the home, as on Updating. It rewrites the .codex/ wiring. When its report says the hooks changed, run /hooks and trust the four entries again.
User-level settings
A few settings belong in ~/.codex/config.toml, not in a home, and the plugin never writes that file. init and upgrade write a note you can paste from, at <HOME>/.state/updates/codex-user-config.md, built from your Claude Code user-level settings.
The note covers telemetry and provider keys, machine preferences, and the model's context window; open the table for why each is user-level.
A line marked # replaces changes a key you already have: edit that line rather than adding a second one, since TOML refuses a duplicate key. Until you paste the note, the home's own profile carries the user-level denies too. Nothing in the note names an agent.
What gets wired
<HOME>/.codex/
├── hooks.json # SessionStart context · SessionEnd + PreCompact capture · PreToolUse guard
├── config.toml # [mcp_servers.agentlayer] with AGENT_HOME · [permissions.agentlayer] profile · shell env policy · [tui] status line
└── rules/agentlayer.rules # one prefix_rule per Bash(…) entry in the Claude settings' ask and deny listsEverything is generated from the home's Claude Code settings, so a permission or a variable is set once and both hosts follow it. The generator merges into existing files, replaces only its own entries, and checks the TOML before writing.
Each piece of the wiring, from the session hooks and the shell guard to the permission profile, the command rules and the model default, is described below.
Current limits
- The session radar (
attention checkpoint all,find-session) reads Claude Code transcripts only. - The profile enables the network inside the sandbox, since an approved escalation does not lift a profile. The outbound gate is the rules file alone, and domain allowlists need Codex's experimental network proxy.
codex exec, the non-interactive mode, cancels MCP calls, so unattended Codex runs cannot use the agent's tools. Interactive sessions are fine.- Native Windows under Codex is unverified: the wiring is shaped to parse under PowerShell, but the skills are bash.
If something's off
Most problems are an unwired home or hooks that aren't trusted yet, fixed with $upgrade and /hooks; find what you see below.
Under the hood
Four implementation details: the hook's context limit, who answers prompts, how shell commands reach hooks, and how skills find the plugin's folder.