Part I: Why, and What's Different

Chapter 1: Introduction — Why Evaluate Codex Now

Written: 2026-04-28 Last updated: 2026-06-11

1.1 If Claude Code Works, Why Reconsider?

If Claude Code already works for you, Codex may look unnecessary. You can open claude, let it read the repository, follow CLAUDE.md, and carry design and implementation through a long conversation. Learning a new tool is a real cost. If several of your projects were built with Claude Code, "moving to Codex" may sound less like an opportunity and more like a burden.

But the longer you use Claude Code, the more small frictions accumulate. Long sessions make it hard to know what context still matters. Limits, throttling, or peak-time quality variance can break the rhythm of work. Good prompts and harnesses can become tied to one tool's conventions. When you move across many repositories, current state, next actions, and verification commands often remain scattered inside conversations instead of being left in a form the next agent can safely inherit.

So the question is not "Claude Code is bad, so should we replace it with Codex?" The better question is this: can we keep the workflow Claude Code helped us build, while adding the Codex surfaces that are useful for small diffs, independent review, sandboxed execution, Worktree mode, and Cloud-backed work?

It is normal for that transition to feel unclear. What should happen to CLAUDE.md? Should the .claude/ harness stay? What belongs in AGENTS.md? How do you let Codex read an existing repository without damaging the path back to Claude Code? This book starts at exactly that point. It is a survey for people who already use Claude Code well and want to evaluate Codex without breaking the workflows that still work.

1.2 Why Now?

Saying "because GPT-5.5 arrived in Codex first" is not a strong enough reason to evaluate Codex. The newest model matters, but it is not the whole argument. GPT-5.5 arriving in the Codex product surface before the API in April 2026 was a signal [7]. It was not the conclusion.

The larger shift is not only model quality. It is delivery. Claude Code already showed that a strong model plus a strong terminal harness can change real developer workflows [1]. Codex is interesting for the same reason. Frontier models are no longer delivered only as API endpoints. They increasingly arrive inside product surfaces that bundle sandboxing, permissions, diffs, review, worktrees, and cloud execution [9].

So the answer to "why now?" has three parts.

Reason What Claude Code users feel Where Codex is worth evaluating
Operational risk Limits, throttling, and peak-time quality variance interrupt work. Keep a second execution surface instead of tying all work to one tool.
Verification units Large changes produced after long conversations are hard to review and roll back. Use small diffs, /review, and sandboxed execution to shrink the change unit.
Knowledge lock-in Rules and current state are scattered across CLAUDE.md, conversations, and tool-specific memory. Move shared knowledge into AGENTS.md, HANDOFF.md, and TASKS.md.

Before Codex is a way to access a newer model, it is a second surface for operating repositories in smaller, more reviewable units. That distinction matters. Without it, the rest of this book becomes a feature checklist instead of a migration method.

Update, 2026-06-11. The post-May shift strengthens this argument. Codex now has an official "Migrate to Codex" path that imports other agent setups: instruction files become AGENTS.md, settings move toward config.toml, slash commands can become skills, and subagents can become Codex agents [9]. That does not make migration automatic. It does mean the main migration question has moved from "can Codex read my Claude Code repo?" to "which pieces of the old harness should become shared rules, which should stay Claude-specific, and which should be rebuilt as Codex skills, agents, hooks, plugins, or automation?"

Figure 1.1: Claude Code dominance and GPT-5.5 landing inside Codex — the moment the harness beat the API to market. illustration by author Gemini assisted

1.3 What People Actually Mean by "Moving"

Since spring 2026, more posts and videos have described moving from Claude Code to Codex. Read closely, most of them are not describing a clean replacement. The practical views fall into five groups.

View Core claim How this book interprets it
Hybrid view Claude Code is the driver for design and judgment; Codex is the worker for implementation and verification [2]. Role separation comes before full migration.
Operational reliability view Claude Code limits, throttling, and peak-time quality variance make Codex useful as a backup or alternative [3]. Depending on one tool for all work is an operational risk.
Verification-loop view Codex has clearer mechanisms for reviewable change units: sandboxing, /diff, /review, and Worktree mode [9]. The more local repositories you maintain, the more small diffs and independent review matter.
Standardization view Moving knowledge from CLAUDE.md into AGENTS.md, HANDOFF.md, and TASKS.md reduces tool lock-in [5]. Migration is mainly knowledge externalization, not tool replacement.
Skeptical view Claude Code can still be better for design, context, and interactive work [6]. The first step is parallel evaluation, not abandonment.

The important move is not emotional tool switching. It is task decomposition. You can keep Claude Code for design, exploration, and long interactive judgment. You can attach Codex where small implementation diffs, independent review, sandboxed execution, Worktree experiments, or Cloud-backed long tasks fit better.

By June 2026, this hybrid view is also more operational. Codex subagents are available by default but are best used for explicit parallel exploration, log reading, and independent review, not as an invisible background swarm [9]. The practical question is no longer "Claude or Codex?" It is "which task belongs in Claude Code, which task belongs in Codex CLI, which task belongs in a Codex Worktree thread, and what handoff file lets either tool recover the state?"

In this book, "migration" is not a one-time event where you replace a tool. It is the process of adding a reviewable execution surface next to a working workflow, validating it on real repositories in small steps, and deciding whether to expand its role.

1.4 The Principle: Parallel Operation, Not Replacement

The first rule is simple. The existing Claude Code workflow must keep working. Evaluating Codex is not a reason to delete or rename CLAUDE.md, .claude/, hooks, skills, or subagents. If Codex does not fit a repository or fails the quality bar, you should be able to return to Claude Code immediately.

This is not just conservative preference. It is operational safety. A Claude Code repository contains more than code. It contains project rules, habits, validation routines, slash commands, hooks, and subagents. That harness is the result of accumulated trial and error. Breaking it during evaluation is not migration. It is an outage.

Codex's first role should be an additional execution surface, not a replacement. At first, it is enough for Codex to read the repository, explain the structure, identify risk files, make one small diff, and review that diff. If it repeatedly produces good results, expand its role. If it feels risky or inconvenient, stop.

This book uses four success criteria.

  1. Claude Code can continue the existing workflow.
  2. Codex changes are small enough to verify with /diff, /review, and tests.
  3. Project rules and current state are left in tool-neutral files.
  4. A failed experiment can be rolled back with git and the existing harness.

If those four conditions are not true, the work is not migration yet. It is a risky experiment.

1.5 The Smallest Unit Is Knowledge, Not the Repository

The expensive part of moving from Claude Code to Codex is not rewriting code. It is moving knowledge.

In many Claude Code projects, important knowledge lives in three places: conversation history, Claude-specific memory, and harness files such as CLAUDE.md and .claude/. If that knowledge stays inside Claude Code, Codex cannot reliably take over. If project rules, current state, next actions, and verification commands are moved into plain-text files, Codex and other tools can take over safely.

Three files recur throughout this book.

File Role
AGENTS.md Tool-neutral project rules, build/test commands, code style, constraints
HANDOFF.md Current state, recent decisions, risk areas, next tasks, verification results
TASKS.md Small backlog items, dependencies, completion criteria

These files do not replace Claude Code. They create a shared work surface that both Claude Code and Codex can read. A good transition does not delete CLAUDE.md; it moves universal knowledge into AGENTS.md and leaves Claude-specific instructions where they belong.

From this perspective, the smallest unit of migration is not the entire repository. It is one piece of knowledge the next agent can inherit: a build command, a test command, a forbidden file, a recent decision. Every time one of those becomes explicit, tool lock-in goes down.

Figure 1.2: Knowledge externalization in practice — only plain-text artifacts (AGENTS.md, HANDOFF.md, TASKS.md) survive the Claude to Codex migration; tool-specific memory and conversation-bound context must be rebuilt. illustration by author Gemini assisted

1.6 Start with the Easiest Repository

The worst first experiment is the repository with the strongest harness. The stronger the Claude Code setup, the more important it is to preserve a path back.

Use this order instead.

  1. Start with a small repository. Choose documentation edits, one test, or a small bug fix.
  2. Begin in Read Only. Let Codex inspect repo structure, CLAUDE.md, .claude/, and build/test commands.
  3. State the no-delete rule. Do not touch CLAUDE.md, .claude/, hooks, skills, or subagents.
  4. Add only minimal scaffold. Create only the AGENTS.md, HANDOFF.md, or TASKS.md files needed for the next step.
  5. Assign one small diff. Keep the scope narrow; inspect /diff, run /review, and test.
  6. Then move to the next repository. Migrate the strongest harness repository last.

This order is not an argument against Codex. Good tools still need safe adoption paths. If Codex works well, expand its role. If it does not, nothing important has been lost.

1.7 Map of the Book

The book has four parts.

Part I: Why, and What's Different (Ch 1-3)

Why evaluate Codex, how it differs from Claude Code, and how to enter an existing repository safely.

Part II: Learning Harness Engineering Anew in Codex (Ch 4-6)

Harness basics, AGENTS.md, configuration, and verifiable vibe-coding loops.

Part III: Practical Codex Guide in the GPT-5.5 Era (Ch 7-9)

Recent model and CLI changes, hybrid community patterns, Worktree, /goal, and meta-harness workflows.

Part IV: From LLM Wiki to the AI Scientist (Ch 10-12)

Personal knowledge management, external memory, and research automation workflows by domain.

Figure 1.3: Map of the book — 4 Parts and 12 chapters. Part I introduces; Part II is fresh harness-engineering learning in Codex; Part III covers the GPT-5.5 era; Part IV moves from LLM Wiki to the AI Scientist. illustration by author Gemini assisted

If this is your first pass, read Chapters 1-3 first, then read Chapters 5-6 before letting Codex touch a real repository. If you already operate many Claude Code repositories, pay special attention to Chapter 3 on taking over local GitHub repositories and Chapter 5 on rebuilding a Claude Code harness for Codex.

This is not a Codex fan book. It is a procedure for Claude Code users who want to evaluate Codex without breaking their repositories.

References

  1. Dev.to, "Claude Code authored ~4% of all public GitHub commits in March 2026," 2026-03. [DEV Community, 2026]
  2. Fountain City, "Claude Code and Codex Together: Driver/Worker Orchestration in Production," 2026-04-30. [Fountain City, 2026]
  3. Reddit r/ClaudeCode, "We have it good, just tried Codex," 2026-04-23. [Reddit, 2026]
  4. OpenAI, "Codex CLI changelog and slash commands," 2026. [OpenAI, 2026]
  5. Daniel Vaughan, "Migrating a Workflow from Claude Code to Codex CLI," 2026-03-26. [Vaughan, 2026]
  6. DevGENT, "GPT-5.5 Codex Review: Pro $100, Claude Max," 2026-04-25. [DevGENT, 2026]
  7. Willison, Simon, "GPT-5.5," simonwillison.net, 2026-04-23. [Willison, 2026]
  8. OpenAI, "Migrate to Codex," 2026. [OpenAI, 2026]
  9. OpenAI, "Codex subagents," 2026. [OpenAI, 2026]
  10. Anthropic, "Claude Code changelog," 2026. [Anthropic, 2026]