MemoryLake
Back to all articles
TutorialNovember 19, 2026·11 min read

How to Migrate Your Codex Hooks to Claude Code Without Losing Context (2026)

Your team has a few Codex hooks that do real work. One checks every shell command against a policy script before it runs. One loads session notes when a chat starts. One reminds the agent to run tests before it stops. You're adding Claude Code to your workflow, you've used /import codex to bring over your instructions and skills, and the first session starts without any of those hooks.

That's expected. Claude Code's commands reference describes /import as bringing configuration from Codex "including instruction files, MCP servers, commands, subagents, and skills." Hooks aren't in that list. Moving them is a manual step.

The good news is that the two tools describe hooks in a very similar shape, so most of the work is translation rather than rewriting. Claude Code's documentation describes three levels of nesting: a hook event, "a matcher group to filter when it fires," and one or more handlers. Codex's documentation describes the same three levels.

This guide covers where hooks live in each tool, what carries over unchanged, what needs translating, which events exist on only one side, how trust works in each, how to move context-loading hooks without losing what they load, and a step-by-step manual migration.

What a hook is in each tool

Codex's documentation describes hooks as "an extensibility framework for Codex. They let you run scripts or MCP tools during the agentic loop". Its list of examples includes "Summarize chats to create persistent memories automatically" and "Run a custom validation check when a chat turn stops, enforcing standards".

Claude Code's documentation says hooks "are defined in JSON settings files" and organized as event, matcher group, and handler. A handler can be a shell command, an HTTP endpoint, an MCP tool, a prompt, or an agent.

Codex supports fewer handler types. Its documentation says: "command and mcp_tool handlers are supported. prompt and agent handlers are parsed but skipped." Since Claude Code supports both of those, every handler that actually runs in Codex has a matching type in Claude Code.

Where hooks live

In Codex, hooks go in a hooks.json file or inline in config.toml. The documentation lists the hooks.json locations:

  • System: /etc/codex/hooks.json on macOS and Linux.
  • User: $CODEX_HOME/hooks.json, which is ~/.codex/hooks.json when CODEX_HOME is unset.
  • Trusted project: .codex/hooks.json.

Codex also loads hooks bundled with enabled plugins. When one layer uses both files, the documentation says "Codex loads both and warns at startup. Prefer one format per layer."

In Claude Code, hooks go in settings files. The documentation's table lists the main locations:

  • ~/.claude/settings.json for all your projects.
  • .claude/settings.json for a single project, which "can be committed to the repo".
  • .claude/settings.local.json for a single project, kept local.
  • Managed policy settings, plugins, and skill or subagent frontmatter.

So a Codex user-level hooks.json maps most closely to ~/.claude/settings.json, and a project's .codex/hooks.json maps to .claude/settings.json, under a top-level hooks key.

What carries over unchanged

Several pieces need no translation.

The structure. Event names, matcher groups, and a list of handlers per group.

The shared event names. SessionStart, SessionEnd, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, PreCompact, PostCompact, SubagentStart, SubagentStop, and Stop appear in both tools' references.

SessionStart sources. Codex lists startup, resume, clear, compact, and fork. Claude Code's SessionStart matcher table lists the same five values.

The common input fields. Both send JSON on stdin with session_id, transcript_path, cwd, hook_event_name, and permission_mode.

Exit code 2. In Codex, several events let you "use exit code 2 and write the blocking reason to stderr." Claude Code also treats exit code 2 as a blocking signal on events that support it, and documents its behavior per event.

Default timeout. Codex uses 600 seconds for most hooks. Claude Code lists 600 as the default for command hooks.

What needs translating

Matchers. Both use the matcher to filter by tool name or start source, but they evaluate it differently. Codex says its matcher "is a regex string". Claude Code treats a matcher made only of letters, digits, and a few separators as exact names, and anything else as an unanchored JavaScript regular expression. A Codex matcher like ^apply_patch$ stays a regex in Claude Code, but the tool name inside it needs changing.

Tool names. Codex's shell tool matches as Bash, which is also Claude Code's name. File edits differ. In Codex, apply_patch can be matched "as apply_patch, Edit, or Write." In Claude Code, the edit tools are matched by names such as Edit and Write. If your Codex hooks already use Edit|Write, that matcher carries over. If they use apply_patch, change it.

MCP tool names. Both use the mcp__server__tool pattern in their examples, so MCP matchers can carry over. Check that the server has the same name in both tools.

Script paths. Codex's examples reference project scripts through Git, with paths under .codex/hooks/. Claude Code offers a placeholder for this: ${CLAUDE_PROJECT_DIR}, "the project root where the session started." If you move scripts into .claude/hooks/, update the paths too.

The model field. Codex lists model as a common input field, a "Codex-specific extension." Claude Code says: "Only SessionStart hooks can receive a model field, and Claude Code doesn't always include it." A Codex script that reads the model on every event needs a fallback.

Turn IDs. Codex adds turn_id to turn-scoped hooks. Claude Code's common fields include prompt_id, which identifies the user prompt being processed. Logging scripts that key on turn IDs need adjusting.

Context limits. Codex's additionalContextLimit field controls how much context a hook can send before Codex saves the full text to disk. Claude Code's handler field table doesn't list that field, so remove it when you copy a handler.

Events on only one side

Codex lists three events that Claude Code's hook reference doesn't include under the same names: PreModelRequest, PostModelRequest, and Interrupt. Codex runs the first two "for each model request attempt", and Interrupt when you interrupt an active turn.

If you rely on those, look for the closest Claude Code event or accept that the behavior won't carry over. Claude Code, in turn, has many events Codex doesn't, such as PostToolUseFailure, Notification, FileChanged, and PreModelSwitch. A migration is a good time to check whether one of them does the job better.

How trust works on each side

Codex trusts hooks individually. Its documentation says: "Before a non-managed hook can run, Codex requires you to review and trust the exact hook definition. Codex records trust against the hook's current hash, so new or changed hooks are marked for review and skipped until trusted."

Claude Code checks workspace trust instead. In an interactive session, it "holds back hooks from every settings file, including your own ~/.claude/settings.json, until you accept the workspace trust dialog for the folder". In a -p or SDK session, it "treats the folder as trusted".

Claude Code's /hooks menu is a read-only browser that shows each hook and where it comes from. Use it after migrating to confirm every hook landed where you expected.

Plugin, managed, and disabled hooks

Not every hook is yours to move.

Plugin hooks travel with their plugin. Codex says enabled plugins can supply hooks "through their manifest or, by default, hooks/hooks.json in the plugin root." Claude Code uses the same file name inside a plugin, and its documentation says that "When a plugin is enabled, its hooks merge with your user and project hooks." If a hook came from a plugin, install the Claude Code version of that plugin rather than copying the hook.

Managed hooks belong to your administrator. Codex marks hooks from system, MDM, cloud, or requirements.toml sources as managed and trusted by policy. Claude Code has managed policy settings, and an allowManagedHooksOnly setting that blocks user, project, local, and plugin hooks. Check with your administrator before recreating a managed hook yourself.

Turning hooks off works differently. In Codex, hooks are enabled by default and turned off with a feature flag in config.toml. In Claude Code, the documented switch is disableAllHooks in a settings file, and it can't disable managed hooks from outside managed settings.

Moving context-loading hooks

SessionStart hooks that load context are the ones most worth getting right, because they shape what the agent knows from the first turn.

In Codex, "Plain text on stdout is added as extra developer context", and a JSON additionalContext field works the same way. Codex also runs SessionStart hooks that match compact after it compacts a session, so the context comes back after a summary.

Claude Code works similarly. Its documentation says that for SessionStart, "Claude Code adds plain-text stdout as context that Claude can see and act on." Its compact source fires after "Auto or manual compaction".

Claude Code adds advice about what belongs in a hook at all. Its SessionStart section says the event is "Useful for loading development context like existing issues or recent changes to your codebase," and then: "For static context that doesn't require a script, use CLAUDE.md".

So if a Codex hook does nothing but print the same conventions every time, the migration is a chance to move that text into CLAUDE.md and keep the hook for context that changes. We covered which Claude Code hooks can add context, and when CLAUDE.md is the better place, in our guide to Claude Code hooks.

What people try first

Expecting /import codex to bring hooks. Its documented list covers instruction files, MCP servers, commands, subagents, and skills.

Copying hooks.json into .claude/. Claude Code's documented locations are settings files, plugins, and skill or subagent frontmatter.

Keeping apply_patch in matchers. Claude Code's edit tools use different names.

Reading model on every event. In Claude Code, only SessionStart can receive it.

Keeping static conventions in a hook. Claude Code recommends CLAUDE.md for static context.

The manual migration

Step 1: List your Codex hooks

Open /hooks in the Codex CLI and note each hook's source, event, matcher, and command.

Step 2: Choose the Claude Code settings file

Use ~/.claude/settings.json for personal hooks and .claude/settings.json for shared project hooks.

Step 3: Copy the structure

Recreate each event and matcher group under the hooks key, converting any TOML hooks to JSON.

Step 4: Translate matchers and paths

Replace apply_patch, check regex matchers, and point script paths at ${CLAUDE_PROJECT_DIR}.

Step 5: Adjust scripts that read Codex-only fields

Add fallbacks for model and turn_id, and remove additionalContextLimit.

Step 6: Move static context to CLAUDE.md

Keep hooks for context that changes. Put fixed conventions in CLAUDE.md.

Step 7: Trust the folder and verify

Accept the workspace trust dialog, then check /hooks and trigger each event once.

The Better Way: Keep what your hooks enforce in one place

Hooks enforce rules and load context. The reasons behind them, such as why a command is blocked, which policy a check implements, or what the session notes are supposed to contain, are project context. When hooks move between tools, the scripts come along, but the reasoning behind them can live only in someone's memory.

MemoryLake is a memory layer for that kind of project context, such as policies, conventions, and the reasons behind your checks, kept in one place you maintain and available to the assistants you connect, such as ChatGPT, Claude Code, and Codex.

You write the entries yourself, in your own words. Nothing is read out of, written to, or deleted from your hooks.json files, your settings files, your hook scripts, your Codex or Claude Code sessions, or any vendor's store. Hooks work the way OpenAI and Anthropic describe them.

Step 1: Create an API key

Sign in and generate a key from the dashboard. Store it outside your repositories, like any other credential.

The MemoryLake console showing the API keys screen, where a new key is created and copied for use in an agent
The MemoryLake console showing the API keys screen, where a new key is created and copied for use in an agent

Step 2: Upload your first memories

Start with the hooks you listed in Step 1 of the manual migration. For each one, write down what it enforces and why. One hook per entry.

The MemoryLake workspace with the first documents uploaded, listing each file as it becomes searchable memory
The MemoryLake workspace with the first documents uploaded, listing each file as it becomes searchable memory

Step 3: Connect your AI & agents

Connect Claude Code, Codex, and the other assistants you use. Each can draw on the same reasons, whichever tool runs the hook.

The MemoryLake integrations screen listing the AI clients and agent frameworks that can be connected to the memory layer
The MemoryLake integrations screen listing the AI clients and agent frameworks that can be connected to the memory layer

What this changes in practice

The first difference is easier translation. When a hook's purpose is written down, you can pick the right Claude Code event even when the names differ.

The second is less duplication. Context that doesn't change goes into CLAUDE.md once, not into a script that prints it every session.

The third is consistency across tools. The same policies and reasons are available in Claude Code and in Codex.

Best practices for moving Codex hooks to Claude Code

Inventory first. Use /hooks in Codex to see every source.

Map files deliberately. User hooks to ~/.claude/settings.json, project hooks to .claude/settings.json.

Translate tool names. apply_patch becomes Edit or Write.

Use ${CLAUDE_PROJECT_DIR} for scripts. It points at the project root where the session started.

Check Codex-only events. PreModelRequest, PostModelRequest, and Interrupt need a plan.

Move static text to CLAUDE.md. Keep hooks for changing context.

Review .claude/ before scripted runs. -p sessions treat the folder as trusted.

Conclusion

Claude Code's /import codex brings instruction files, MCP servers, commands, subagents, and skills, and hooks aren't in that documented list. Moving them by hand is mostly translation, because both tools use the same three levels: event, matcher group, and handlers. Most event names, the SessionStart sources, the common input fields, exit code 2, and the default timeout carry over.

The changes are in the details: matchers are evaluated differently, apply_patch needs a Claude Code tool name, script paths should use ${CLAUDE_PROJECT_DIR}, and scripts that read model, turn_id, or additionalContextLimit need adjusting. Codex trusts each hook by hash, while Claude Code checks workspace trust. Use the move to put static context into CLAUDE.md and keep hooks for what changes.

Frequently asked questions

Does /import codex bring over Codex hooks?

Claude Code's reference lists instruction files, MCP servers, commands, subagents, and skills. Hooks aren't in that list.

Where do hooks go in Claude Code?

In settings files such as ~/.claude/settings.json or .claude/settings.json, under the hooks key.

Can I reuse my Codex hooks.json structure?

Mostly. Both use events, matcher groups, and handlers. Translate tool names and paths.

What replaces apply_patch in a Claude Code matcher?

Claude Code's edit tools, such as Edit and Write.

Do Codex SessionStart hooks work the same way in Claude Code?

Both add plain-text stdout as context and support the same start sources.

Which Codex hook events have no same-named Claude Code event?

PreModelRequest, PostModelRequest, and Interrupt.

Do I need to trust hooks again in Claude Code?

Claude Code holds back settings-file hooks until you accept the workspace trust dialog in an interactive session.