Skip to content

Claude Code and Codex: migrating without picking a side

By Updated at 3 min read

After hearing Codex this, Codex that, while also dealing with disastrous communication from Anthropic and hitting yet another set of usage limits, it feels like the right time to try Codex and the latest OpenAI models, which are said to have caught up with Anthropic’s.

Claude Code et Codex ouverts côte à côte dans plusieurs terminaux

So I am migrating my projects to Codex, but without giving up Claude Code.

The migration took more than a single prompt and a yolo run. Until then, my skills and documentation had been organized around Claude Code.

The goal is to maintain one setup instead of two configurations, while keeping the freedom to move from one tool to the other.

The migration followed one rule: one physical source for each instruction, with as few adapters as possible at each tool boundary.

Below, I explain the resulting architecture, the mistakes I encountered, how I now use Claude Code and Codex on the same projects, and which one I prefer.

Two tools, two conventions

Claude Code and Codex can both receive project instructions and run reusable workflows, but they do not look for them in the same places.

NeedClaude CodeCodex
Project instructionsCLAUDE.mdAGENTS.md
Project skills.claude/skills/.agents/skills/
Manual skill invocation/my-skill$my-skill or /skills
Automated executionclaude -pcodex exec

Codex loads AGENTS.md files from the global level down to the current directory. Its skills are directories that contain a SKILL.md file, optionally supplemented with scripts, references, assets, and metadata. This behavior is described in the official documentation for AGENTS.md and Codex skills. I therefore needed to adapt the entry points of my workflows to each tool without rewriting them.

Keeping ~/.claude as the shared Git repository

My ~/.claude user directory was already versioned and synchronized with Git. I kept it as the canonical repository, read directly by Claude Code for its settings and skills.

An install.sh script then exposes each compatible skill in ~/.agents/skills/ through a symbolic link to the original:

~/.claude/skills/document/
              ↑
~/.agents/skills/document

The link guarantees that both paths point to the same skill. The installer is idempotent. It preserves physical Codex skills and can exclude a Claude skill with .codex-skip, as it does for skill-creator.

It also merges the status line configuration into ~/.codex/config.toml without overwriting the rest of the local configuration.

On a new machine:

git clone git@***/.claude.git ~/.claude
~/.claude/install.sh

After installing Codex on a VPS, any skill pushed from my workstation becomes available there by running git pull, followed by install.sh.

Turning old commands into tool-neutral skills

My old Claude commands were converted into skills, then cleaned up:

  1. Removed the model and version fields that tied a workflow to one provider.
  2. Replaced imperative wording such as call /skill with tool-neutral instructions.
  3. Replaced mandatory references to Claude in Chrome with a generic browsing capability, using dev-browser as a portable implementation.
  4. Added a separate control for strictly manual skills.

For the last point, Claude Code reads disable-model-invocation: true from SKILL.md. Codex uses allow_implicit_invocation: false in agents/openai.yaml. The workflow remains available, but the agent will not launch it on its own.

Other skills can still be invoked implicitly. Codex documents both activation modes: explicit invocation with $skill, or automatic selection based on the description.

One project instruction file

I applied the same rule to project repositories:

AGENTS.md              canonical file
CLAUDE.md -> AGENTS.md symbolic link

For local skills, one of the two directories contains the physical files and the other points to it. Depending on the project’s history, either the entire directory or each individual skill is linked.

Hook configuration is the exception to this rule. It must be adapted separately for Claude Code and Codex.

Making automated calls interchangeable

Sharing files was not enough. Several applications called claude -p directly from PHP, Node.js, Bash, cron, or systemd.

I placed each call behind an adapter controlled by one common variable:

AI_AGENT_PROVIDER=codex

This choice now lives in each project’s .env file. The systemd services and cron entries remain provider-neutral. They launch the application, then the adapter reads only the permitted AI_AGENT_* keys. Other secrets from .env are not passed to the agent subprocess.

To test the other provider for a single run, a variable placed before the command takes precedence over the file:

AI_AGENT_PROVIDER=claude ./script/my-task

For Codex, non-interactive tasks use codex exec, the command designed for scripts and CI. The CLI documentation also describes the read-only, workspace-write, and danger-full-access sandbox modes.

This migration mainly removed Claude-specific assumptions from my workflows. Porting from Claude to Codex was only the starting point.

I came away with two organizational principles:

  1. Git synchronizes machines, while symbolic links guarantee local uniqueness. One does not replace the other.
  2. Domain-specific instructions should remain provider-neutral. The provider, model, sandbox, and output format belong in the adapter.

When it comes to publishing, an agent should not control the entire publication chain. A probabilistic repair can feed into a deterministic procedure, but it should not replace it.

I can now open the same repository with Claude Code or Codex and invoke the same skills. My automations run with either one. Codex has become the active agent on the server without turning Claude Code into a legacy system that must be removed.

The most valuable result is that the next switch will cost far less.

Claude Code or Codex: my experience after one day of testing

Although this is not the main subject of the article, here is my personal feedback after one day of use for anyone considering a migration.

I had already compared Claude Code and OpenCode. Moving to Codex adds a change of model and ecosystem this time, not just a different interface.

The Claude Code CLI is much more pleasant and polished than Codex. That comfort comes down to a few very practical details:

  • the last prompt I sent remains visible on one line. Clicking it takes me back to the full message in the history;
  • the input field can expand, and I can place the cursor with the mouse;
  • Claude Code asks interactive questions with selectable answers (radio buttons), checkboxes, and/or a free-text field;
  • chats can now exchange messages between sessions. I use this in particular between one session dedicated to a specific project and another dedicated to a shared foundation used by several projects.

For everything else, I do not have a conclusion yet. I am using Opus 5 against GPT-5.6-sol, with the reasoning level set to high or xhigh, but this section is not intended to compare the models. One day is not enough to judge speed, code quality, or debugging performance.

I will use Codex intensively for a month before deciding whether it becomes my primary interface or whether I return to Anthropic at the end of September. I will record what happens next in my AI adoption journey, which I update regularly.

AI, SEO and Web strategy session

Planning a coding-agent migration?

Separate business instructions from the provider, estimate the porting effort, and secure the transition before moving your automations.

Challenge my AI architecture

€350 excl. VAT, up to 90 minutes

Email • RSS • Twitter

Get notified of new posts

Continue reading: