Claude Code to Codex Migration Guide 2026

On May 3, 2026, I inventoried 744 local agent-configuration entries, then ranked 691 of them by operational weight.¹ The count looked large. The shape mattered more: roughly 20 files carried the system.

A Claude Code to Codex migration should port operating contracts, not copy the file tree. Move CLAUDE.md rules into layered AGENTS.md, reusable procedures into Codex skills, deterministic gates into focused hooks, risk posture into profiles, and browser/source tooling into explicit MCP. Do not copy a Claude hook lattice into Codex; move the proof obligations.

TL;DR

The private writing and verification stack already exists in my Codex world. The missing piece was not the skill content. The missing piece was the public operating manual: where reusable skills should live, how Codex should select them, which profile should run public writing, and which Claude-era gates should become Codex-native rules without exposing private workflow details.

The first live Codex pass changed the migration rule: do not make a private workflow ambient the moment it is ported. Stage it. My site-specific writing path now starts explicit-only, while the migration workflow lives as a user skill for active local use and as a private Codex package candidate for local testing. That package is not open source or generally available; if you want to test the migration workflow, contact me. The package should not become the default runtime path just because a local install entry exists. A real install pilot still needs package validation, plugin install verification, namespaced skill discovery, duplicate cleanup, and a fresh Codex session before it means anything. That lets the system learn from real work before a workflow becomes default behavior.¹⁸¹⁰¹⁴

Do not start by cloning every Claude hook into Codex. Start by writing the Codex contract:

• Put durable cross-repo policy in ~/.codex/AGENTS.md.
• Put repository policy in AGENTS.md, and place narrower overrides close to the work.
• Put reusable procedures in .agents/skills or $HOME/.agents/skills.
• Promote public writing to careful-review or a dedicated public-writing profile.
• Keep deterministic gates as hooks, but treat hooks as one guardrail, not the whole safety model.

The first successful migration artifact should be a self-describing post. That artifact proves the system can describe itself, cite current docs, use a sanitized local inventory, and produce public work under Codex control without publishing the private machinery behind it.

I covered the Claude side of the stack in Claude Code as Infrastructure, the instruction-file side in AGENTS.md Patterns, and the skill decay problem in Static Skills Are Dead Skills. The migration below connects those threads to the Codex runtime I actually use.

For adjacent context, read the Codex CLI guide, Claude Code vs Codex, Codex vs Claude Code 2026, Claude Code Hooks Tutorial, Building Custom Skills, and Jiro Quality Philosophy. Those posts explain the pieces that the migration assembles here.

What Did the Migration Inventory Show?

The local system had three centers of gravity.

The usage data pointed at the same conclusion. My profile routing logs showed that review-heavy work dominated routine execution.¹ The real heart was not the longest file or the cleverest script. The heart was the decision layer that chose risk level, loaded doctrine, and forced evidence before completion.

That finding changes the port.

If the important thing were “Claude has many hooks,” the migration would copy hooks. If the important thing were “the system has a philosophy,” the migration would copy prose. The inventory showed a different answer: the important thing is a small contract that fires at the right time.

What Did We Do Before Publishing?

The article itself became the first migration exercise.

First, I mapped the shape of the mature Claude Code setup: which pieces governed behavior, which pieces only documented preferences, and which pieces should stay private. Then I checked current Codex behavior against official docs and the local CLI, because migration guides decay quickly when they inherit old flags or unsupported config shapes. Then I drafted this article with the real migration in mind, but reduced the public detail to sanitized architecture, not private implementation.

The next step happens before publication: use this guide to build out the Codex setup, then revise the article from what actually changed. The public article should show the migration pattern and the acceptance criteria. It should not publish private prompts, private writing workflows, exact hook internals, sensitive paths, or anything that would let a reader reconstruct the private system.

The live pass produced a public-safe proof table. I am publishing only the contract, activation state, and acceptance signal, not the private prompts, exact hook bodies, or writing workflow internals.

Should You Start a Codex Migration With Hooks?

Claude taught me to think in lifecycle events. A UserPromptSubmit hook can inject project context. A PreToolUse hook can block sensitive paths. A Stop hook can refuse weak completion. That pattern works in Claude because my local stack grew around dispatchers that turn many small scripts into one ordered event pipeline.¹¹

Codex has hooks too, but current Codex treats them as a feature-gated lifecycle system rather than an always-on hook directory. OpenAI’s hooks doc shows [features] codex_hooks = true in config.toml, and my local codex features list reports hooks as stable and enabled on Codex CLI 0.130.0.²⁸ OpenAI documents hook input as JSON on stdin, with shared fields such as session id, working directory, event name, and active model.² Codex supports events such as SessionStart, PreToolUse, PermissionRequest, PostToolUse, UserPromptSubmit, and Stop; PreToolUse can intercept Bash, apply_patch, and MCP tool calls.²

The same documentation also gives the warning that matters for migration: PreToolUse remains a guardrail, not a complete enforcement boundary. The docs note that interception does not cover every shell path and does not intercept web search or other non-shell, non-MCP tool calls.²

That limitation does not make Codex hooks weak. It means hooks should not carry the whole port. OpenAI also notes that multiple matching command hooks for the same event launch concurrently, so a Codex port that requires ordering still needs a dispatcher or one combined hook command.²

For Codex, I want hooks for narrow deterministic checks:

• Block obviously destructive shell commands.
• Warn on credential-shaped paths.
• Add small session-start context.
• Record evidence from public-writing runs.
• Fail a stop event when a required artifact or verification command is missing.

I do not want hooks to carry writing voice, citation policy, philosophy, routing, or project doctrine. Codex already has better homes for those.

How Do Claude Artifacts Map to Codex?

The migration gets cleaner when every Claude artifact maps to the Codex primitive that best matches its job.

OpenAI’s AGENTS.md docs make the first row the migration spine. Codex reads AGENTS.md files before work, layers global guidance from the Codex home directory, then walks from the project root to the current directory, letting closer files override earlier guidance.³ That behavior matches what I actually need from CLAUDE.md: persistent working agreements plus project-local specifics.

The important move: rewrite the rules as operations. “Write with care” does not belong in AGENTS.md. “For public posts, gather citations first, verify URLs, run banned-phrase checks, and report any unverified claims” belongs there.

How Should Private Writing Skills Move to Codex?

The blog writer stack ports cleanly because it already has the right shape. A Codex skill is a folder with a SKILL.md file that contains frontmatter and instructions. Codex can activate skills when the user invokes them explicitly or when the task matches the skill description.⁴ Codex reads skills from repository, user, admin, and system locations, including repo .agents/skills, $HOME/.agents/skills, and /etc/codex/skills.⁴

This is where a Claude Code migration can get subtly wrong. Codex skills are not Claude slash commands. The official Codex skill path for explicit invocation is the skill selector or a $skill-name mention, while Codex CLI slash commands are a separate interactive control surface for built-in actions such as status, permissions, model changes, plugins, and session control.⁴¹⁵ A prompt like /cave can still be useful shorthand if the skill description recognizes it or a wrapper turns it into Use $cave ..., but the slash text itself is not the durable contract. For migration proof, test $skill-name; then test /name separately only if you promise that compatibility.

That means I should normalize new Codex-native writing skills into the official skill paths without publishing the private skill names or contents:

$HOME/.agents/skills/source-verifier/SKILL.md
$HOME/.agents/skills/public-post-writer/SKILL.md
$HOME/.agents/skills/site-specific-writer/SKILL.md

My local runtime also has working user skills in an older location.¹ I should not delete those just because the public docs name .agents/skills. The safe migration is:

1. Copy or symlink one skill into $HOME/.agents/skills.
2. Restart Codex.
3. Confirm Codex lists and activates the skill.
4. Make the skill explicit-only while it is in pilot.
5. Move the rest only after discovery and pilot use work.
6. Leave the old path in place until existing sessions and scripts stop depending on it.

That is the path I took for the first private writing workflow. I staged a site-specific writer as an explicit-only private skill rather than making it the default writer for every content task. That gave the migration a better test: if the skill improves this article and the next public-writing run without leaking private process, it can move from explicit-only to pilot. If it adds confusion, it stays scoped.

Brand-specific writers should not become default site writers. A private product writer may share the same citation and review standards, but its audience, product facts, calls to action, and voice rules should stay scoped to that product. The correct port keeps brand adapters separate and creates a thin site-specific writer for blakecrosley.com.

That site skill should stay thin:

---
name: site-specific-writer
description: Write public technical posts for a specific site. Use for articles that need verified sources, internal links, site voice, and publication checks.
---

# Site-Specific Writer

Use the private writing, source-verification, and AI-discoverability skills for every public technical article.

Required proof before final:
- External technical claims have citations.
- Current Codex claims cite OpenAI docs.
- Internal claims link to existing posts or author analysis.
- The post includes a TL;DR, role-specific takeaways, and reader questions when useful.

Codex skill docs show name and description as the manual skill frontmatter fields, and they make the description the trigger for implicit activation.⁴ The body can tell Codex to use private companion skills; composition belongs in instructions unless a local toolchain adds extra metadata. The general stack owns the writing rules. The site wrapper owns voice, link patterns, and proof.

The same split applies to the migration workflow itself. OpenAI’s plugin docs recommend starting with a local skill when you are still iterating on one personal workflow, then building a plugin when you want to share a stable package across teams or bundle more integrations.¹⁰ That made the active path obvious: user skill first, private package pilot second. I have not open-sourced the migration skill or promised a public release; if you want to test it, contact me. A plugin-cache probe showed that an installed plugin skill appears under a plugin namespace rather than the bare skill name, so package docs should distinguish direct skill use from plugin-installed skill use.⁸

The private package needs a validator before it needs a launch story. In the latest pass, I added a validator that checks the marketplace JSON, plugin manifest, skill frontmatter, required references, citation-checker syntax, install policy, absence of active hook or MCP manifests, generated files, and obvious private-path or secret-fixture leaks. That check belongs before any wider activation because OpenAI’s plugin docs make the marketplace the install surface, not a scratch area for unstable private workflow.⁸¹⁰

How Should AGENTS.md Carry Public Writing Rules?

The strongest Codex migration change belongs in AGENTS.md, not in a hook. Public writing needs a default risk class.

Here is the rule I want near the top of the global or project file:

## Public Writing Is Product Work

Public articles, guides, landing pages, docs that shape user understanding, and product copy use `default` profile at minimum. Promote to `careful-review` when claims, citations, brand, money, safety, security, or user trust are at stake.

Before finishing public writing:
- Gather citations before drafting.
- Cite official product docs for current tool behavior.
- Label author analysis clearly.
- Run a banned-phrase scan.
- Verify internal links.
- Report any claim that could not be verified.

That rule fixes the flaw I found in the router inventory. Some content work had drifted toward fast execution because the router treated “content” as cheap work. Public writing is not cheap work when it changes what people believe, buy, install, or run. Blog drafts, guides, and product pages deserve more review than routine code edits because the failure mode is public trust, not a local test failure.

The post you are reading is the example. It cites current Codex docs for current Codex behavior. It labels local inventory claims as author analysis. It uses a real stack instead of pretending the migration starts from a blank machine, but it keeps private implementation details out of the public article.

How Should Codex Profiles Encode Risk?

OpenAI’s config reference defines profile as the default profile at startup and supports profile-scoped overrides for supported configuration keys.⁵ The same reference defines model_reasoning_effort, approval_policy, and sandbox_mode as explicit configuration controls.⁵

That gives Codex a natural place to encode risk.

[profiles.public-writing]
model = "gpt-5.5"
model_reasoning_effort = "xhigh"
sandbox_mode = "workspace-write"
approval_policy = "on-request"
web_search = "live"

The exact model can change. The policy should not. Public writing needs higher reasoning, live source checking when facts can change, workspace-limited execution, and human approval for actions that leave the safe working path.

The router should map tasks like these to public-writing or careful-review:

• A blog post, guide, or homepage change.
• Any article with citations.
• Any content that compares tools or vendors.
• Any post that names current Codex, Claude Code, OpenAI, Anthropic, Apple, Google, or another fast-moving product.
• Any work that touches schema, llms.txt, SEO, analytics, or public metadata.

The profile is not a vibe. The profile is a risk budget.

Which Codex Hooks Still Matter?

Codex hooks should enforce the small things that must happen at runtime.

A public-writing stop hook could check the changed files and refuse completion if a public Markdown post contains footnote references without definitions. A pre-tool hook could warn if the agent tries to edit .env, analytics credentials, or generated translation caches while writing an article. A session-start hook could add the current date and remind Codex that “latest” claims require verification.

Keep the hook payload small. OpenAI documents JSON output shapes for hooks, including systemMessage, continue, and event-specific fields.² Use those fields to block or warn on exact failures. Do not rebuild the whole Claude dispatcher lattice unless the Codex failure data proves you need it.

Setup tests do not earn promotion. A hook moves out of pilot only after a real-use watch pass shows three things: it fires in the intended situations, it passes ordinary work, and it records safe aggregate telemetry rather than private content. If a block fires, the reason must tell the user what to do next.²⁸

After the first live passes, the practical hook backlog looks like this:

1. SessionStart: keep compact current-date, currentness, project, and public/private boundary context in pilot.
2. PreToolUse:Bash: keep the narrow destructive-command and credential-read guard in pilot.
3. PostToolUse:apply_patch: keep the non-blocking quality shadow on changed code/config patch lines.
4. Stop: keep the changed-public-Markdown citation gate in pilot.
5. Stop: keep the final-verification contract folded into the existing quality Stop pilot; do not create a separate summary hook until real failures prove the need.

That set ports the safety behavior without importing months of Claude-specific ceremony.

How Should MCP and Browser Tools Fit?

My current Codex setup already uses a private MCP-backed browser automation path.¹ Codex also supports MCP servers through both the CLI and config.toml: codex mcp add can register a stdio server, and [mcp_servers.<server-name>] tables can define command, args, environment, URLs, enabled_tools, disabled_tools, and timeouts.⁶

For public writing, MCP belongs in two places:

• Browser automation for checking live rendered pages, screenshots, and local previews.
• Source discovery or docs retrieval when a specific provider exposes a reliable MCP server.

MCP should not hide the source trail. A blog writer needs citations that a reader can click, not a private tool result that only existed inside the session. MCP can help find the fact. The final post still needs a public source.

How Do You Bootstrap a Claude Code to Codex Migration?

The first Codex-native artifact should describe the port while using the port.

Here is the interactive bootstrapping loop:

codex -p careful-review --search \
  "Inventory the local Codex and Claude migration surface, then create a citation bank for a sanitized post about moving the setup to Codex."

codex -p careful-review \
  "Draft content/blog/claude-code-to-codex-migration.md using the local inventory, official Codex docs, and existing internal posts. Label author analysis clearly."

codex -p careful-review \
  "Review the draft for unsupported claims, stale Codex flags, broken internal links, and AGENTS.md operational value."

For non-interactive work, use codex exec and make live search a config/profile concern rather than copying the interactive --search flag. OpenAI documents codex exec for scripted or CI-style runs, with --profile, --sandbox, and --config overrides; my local Codex CLI 0.130.0 help confirms those flags and rejects codex exec --search.⁷⁸

codex exec -p careful-review -c 'web_search="live"' \
  "Create a citation bank for content/blog/claude-code-to-codex-migration.md from official Codex docs and sanitized local inventory."

codex exec -p careful-review \
  "Review content/blog/claude-code-to-codex-migration.md for unsupported Codex claims, stale flags, broken internal links, and AGENTS.md operational value."

The command-line details matter. OpenAI marks --full-auto as a deprecated compatibility flag and recommends --sandbox workspace-write instead.⁷ Old guides that center --full-auto should not control new automation.

The post becomes the acceptance test. If Codex can:

• Load the writing skills.
• Use careful-review.
• Cite current OpenAI docs.
• Use local inventory without exposing private implementation details.
• Explain what changes in AGENTS.md, skills, hooks, profiles, and MCP.
• Produce a clean Markdown article in the site repo.

Then the writing port works.

Claude Code to Codex Migration Checklist

For Codex configuration:

• Add or update ~/.codex/AGENTS.md with global working agreements.
• Add repository AGENTS.md rules for public writing.
• Create public-writing or route public writing to careful-review.
• Make careful-review actually use high or xhigh reasoning for public claims.
• Add a router rule that treats guides, blog posts, docs, and product copy as public-surface work.

For skills:

• Move or mirror private writing skills into $HOME/.agents/skills one at a time.
• Keep actively tested migration workflows as user skills before treating a plugin package as the runtime path.
• Use $skill-name as the canonical explicit invocation test; treat /name as a convenience wrapper or selector habit, not as proof that a Codex skill loaded.
• Add a package-readiness validator before marketplace activation.
• Add a harness-health gate that proves AGENTS references, profiles, skills, hooks, package state, registry shape, and activation state before promotion.
• For install pilots, verify marketplace add, plugin read/install, plugin listing, skill listing, fresh-session skill visibility, and duplicate marketplace cleanup.
• Keep pilot skills explicit-only before allowing implicit activation.
• Keep generic writing standards separate from site-specific voice.
• Keep source verification as the hard factual gate.
• Keep AI-discoverability checks separate from author voice.
• Create a thin site-specific writer skill instead of reusing a brand-specific writer.
• Confirm Codex discovers skills after each move.

For cross-agent collaboration:

• Keep Codex as owner of the loop.
• Anchor reviews to real files or context artifacts.
• Fail closed when anchors are missing, output is empty, or the second agent times out.
• Reject unsupported second-agent findings with local evidence.
• Accept only grounded findings, apply the smallest fix, rerun static review, and then run Codex-owned checks.

For hooks:

• Port only deterministic checks first.
• Use SessionStart, PreToolUse, PostToolUse, and Stop for narrow gates.
• Log failures before adding more gates.
• For shadow hooks, log categories instead of raw private content.
• Test one known-bad fixture and one known-noisy fixture before promotion.
• Split clean failures from cleanup debt before enforcing a migrated check.
• Treat hooks as runtime checks, not as the canonical doctrine store.

For writing workflow:

• Gather citations before drafting.
• Use official docs for current Codex behavior.
• Use author analysis for local inventory and experience.
• Link internal posts where they already explain a concept.
• Run verification before final.
• For guide maintenance, verify source and runtime claims, sync derived public surfaces, regenerate discovery files, and name skipped translation, deploy, and live checks.
• For translated guides, record the selected translation provider, differential batch or section count, credential state without values, whether writes/uploads occurred, locale verification, and the no-write reason when execution is blocked.
• After deploy, verify the canonical URL, structured data, sitemap, and llms-full.txt on production.
• If a CDN cache serves an old 404, purge only the affected public URLs through the existing deployment path.

FAQ

Do private writing skills need to be public?

No. A migration article can describe the shape of the writing system without publishing the private skill names, prompts, scoring details, or brand-specific adapters. The public lesson is where those skills belong and how Codex should activate them.

The migration skill follows the same rule. It is private today, not an open-source package. If you want to test the workflow, contact me.

Should a Claude Code to Codex migration reuse brand-specific writers?

No. Brand-specific writers should stay brand-specific. A personal or company site needs a thin site adapter that shares verification standards without inheriting another product’s audience, facts, or calls to action.

Should I copy every Claude Code hook into Codex?

No. Copy behavior only after identifying the contract behind it. A credential block belongs in a hook. A writing rubric belongs in a skill. A risk rule belongs in a profile or router. A philosophy belongs in AGENTS.md plus a focused skill.

Where should Codex skills live?

For new Codex-native work, use the official skill locations: repo .agents/skills for project skills and $HOME/.agents/skills for user skills.⁴ If an existing local setup also uses ~/.codex/skills, keep it until Codex discovery confirms the new location works.

Why do /skill prompts sometimes fail in Codex?

Because /skill is not the canonical Codex skill invocation contract. Codex skills activate when you select or mention the skill explicitly, including $skill-name, or when the task matches the skill description.⁴ Codex CLI slash commands are their own built-in command surface.¹⁵ Use $skill-name when you need deterministic skill activation. Keep /name only as a convenience wrapper, selector habit, or prompt phrase that still needs its own proof.

What is the heart of a Claude Code to Codex migration?

The heart is not hooks, skills, or profiles alone. The heart is the decision layer that answers four questions before work starts: what kind of work has arrived, what risk profile should run it, what instructions govern it, and what proof must exist before completion?

Key Takeaways

For Codex users: Port contracts, not directories. AGENTS.md, profiles, skills, MCP, and hooks each have a job. Put each rule where Codex will honor it most directly.

For Claude Code users moving over: Treat Codex hooks as guardrails, not as a full replacement for a mature Claude dispatcher system. Start with AGENTS.md and skills, then add hooks where runtime enforcement matters.

For public writers: Blog writing belongs in a high-review profile. Current claims need current sources. A polished wrong article damages trust faster than a broken local script.

For my own stack: The private writing system is no longer just ported in substance; the first site-specific writer is staged as explicit-only, the migration workflow is active as a user skill, and the private plugin package has passed a local install pilot without becoming a public release. The Codex doctrine now makes quality and taste an operating rule. The final-verification summary stayed a manual shadow review, with its narrow deterministic check folded into the existing quality Stop pilot instead of a separate hook. A compact SessionStart context hook is in pilot, the first active quality hook watches apply_patch changes in shadow mode, the first pre-Bash safety guard runs as a narrow blocking pilot, the citation checker now runs as a changed-public-Markdown Stop pilot, guide-maintenance passes proved the source-to-render loop on real public docs, one pass corrected stale exact-count claims instead of preserving old source-harness numbers, another caught a generated-versus-served AI-discovery route mismatch, recent passes corrected model/parameter compatibility, benchmark/model-card drift, fast-moving plugin release drift, rendered FAQ structured-data drift, credit-accounting drift, third-party-only API/legal/feature-minimum claims, and frontmatter-slug route drift, and the latest Codex guide passes made guide translation provider-selectable, used Codex as the default provider for Codex-owned work, rejected truncated translation output before cache write, completed locale writes, verified locale routes, and resolved stale CDN responses with targeted purge instead of silently depending on a Claude-only path. A source-intelligence pass proved dry-run/write-volume discipline before private-memory writes, the company-blog onboarding path now stops before file generation unless target/path/intake evidence are explicit, the blog translator now stops before write execution when D1 credentials or an explicit target are missing and refuses residue-heavy Codex output before publication when credentials are present, a cross-agent collaboration loop proved review/fix/re-verify without handing authority to the second agent, and a manual harness-health gate checks the deterministic promotion surface before any wider activation. The next work is to keep proving the remaining explicit-only production rituals, keep the public release boundary parked, and keep running real public-writing and engineering work through the staged lanes before widening any gate.

References