Claude Code to Codex Handoffs: Three Ways to Preserve Context

Jun 25, 2026 Updated Sep 16, 2026

Article cover for “Claude Code to Codex Handoffs: Three Ways to Preserve Context” over a pastel ringed planet and orbital lines

What you’ll learn

Criteria for dividing workflow stages between Claude Code and Codex
How to record current state, completed work, remaining tasks, and cautions in a handoff document
How shared rules and session boundaries reduce context loss between AI tools

Document Context When Handing Work Between Claude Code and Codex

To hand work from Claude Code to Codex without changing the decision criteria, record current state, completed work, remaining tasks, and cautions in a document the next tool can read. Conversation continuity alone can leave scope and verification results implicit. A handoff document, shared rules, and deliberate session boundaries keep the transfer reviewable while reducing repeated explanation.

By the end of this article, you will have practical criteria for answering “What should a handoff document preserve so the next AI resumes with the same decision criteria?” in your own context.

Handoff Design Covers Tool Choice, Context Loss, and State Storage

A handoff bridge carrying current state, completed work, remaining tasks, cautions, and shared rules to the next AI

This site uses two AIs — Claude Code and Codex — in the same repository. I switch between them depending on the type of work, and I sometimes hand off mid-task from one to the other.

This article covers three topics:

The types of work each AI suits and the criteria I use to choose between them
Why context breaks when handing off between sessions
Three approaches for preserving context across that handoff

The Basic Difference Between Claude and Codex

Claude Code is a coding agent that can read a codebase, edit files, run commands, and integrate with development tools. It is available not only in the terminal, but also in IDEs, the desktop app, and the browser.[1] I mainly use it in the IDE, and I use it conversationally when a task needs creative judgment, such as initial planning, design discussion, or isolating the cause of an error.

Codex (OpenAI) is also a coding agent for writing, understanding, reviewing, debugging, and automating development work.[2] Current Codex surfaces include an interactive CLI, IDE extension, desktop app, and Web/Cloud mode for background execution.[3][4][5] I also mainly use Codex from the IDE, and I lean on it when I want a larger diff or review result to inspect afterward.

This article is not a complete feature comparison between Claude Code and Codex. Model updates move quickly, so frankly, I adjust how I use them each time after checking the character of the updated models. On this site, I currently lean on Claude Code for planning and design discussions, and on Codex for larger changes, repeatable reviews, and implementation passes.

I Give Planning, Error Investigation, and Direction-Setting to Claude Code

I often give Claude the creative work: initial planning, design discussions, and early judgment calls.

Planning and design decisions: When the right approach is not obvious — “how should this feature be implemented?” or “does this structure cause any problems?” — working through it in conversation with Claude is useful. Because I can compare alternatives while checking the reasoning, I can accumulate decisions and keep moving.

Error investigation: When an error occurs, identifying the cause involves forming and testing multiple hypotheses. When a task requires dialogue — “what does this log mean?” or “what should I check next?” — Claude is a good fit.

Shaping the direction: I also use Claude to discuss an article or feature’s purpose, the order in which to explain it, and which decisions should be settled first. It is useful at the ambiguous stage before implementation, when I still need to organize options.

I Give Batch Transformation and Criteria-Based Review to Codex

I give Codex tasks that follow a fixed pattern, can be repeated, or are easier to review as a larger diff. In my workflow, Codex has high prompt fidelity and is strong at detecting issues against review documents. Codex CLI can also be used interactively, but on this site I often use it by giving instructions, reviewing the resulting changes, and then adding follow-up instructions if needed.[3]

Bulk transformations following the same pattern: “Add the same frontmatter (the metadata at the top of a Markdown article, such as title, description, and date) field to all files in this directory” is a task well suited to Codex. When the change pattern is clear and there are few mid-task judgment calls, the resulting diff is easier to review as a whole.

Bulk review based on review documents: When I hand Codex a list of target files and a review document, asking it to check each file against the same criteria is a good fit. The more clearly the criteria are written down, the easier it is to inspect the detected issues afterward.

Set Direction in Claude Code and Hand Repetitive Work to Codex

At one point I had several English versions of blog articles to create.

I started with Claude Code. I reviewed the Japanese source content, discussed translation decisions, and built the first article together. At that stage, judgment was needed — “how do I translate this?” and “how do I convey this Japanese context in English?” — so the conversational format of Claude was appropriate.

Once the first article was done, the translation pattern was clear. The remaining articles just needed to follow the same pattern. I handed off to Codex and gave it instructions to create the remaining English versions in bulk.

The flow was: establish the approach with Claude, then hand the repetitive portion to Codex.

Choose Claude Code or Codex by Mid-Task Judgment and Repetition

When deciding which AI to use, I check the following:

Question	Points to Claude Code in this workflow	Points to Codex in this workflow
Does the task require judgment mid-way?	Yes	No
Do I want detailed real-time verification?	Yes	No
Is the task a repeating pattern?	No	Yes

Codex also has an interactive CLI and IDE extension, and Claude Code also has web and desktop surfaces. This table is therefore not a statement about product limits. It is a practical guideline for how I use them on this site. There is no requirement that one AI handle everything. Handing off mid-task is also an option.

Use Git History to Inspect the Division of Work Between Claude Code and Codex

This division of labor is not based only on intuition. When I grouped the local Git history as of June 24, 2026 into Claude-related paths, Codex-related paths, and shared harness (the set of rules, procedures, and validation that guides AI work in a project) paths, the pattern matched how I use the tools.

This count does not prove which model created each commit. It is a repository-path view: CLAUDE.md, .claude/, and Claude-related docs/blog content are counted as Claude-side paths; AGENTS.md, .codex/, and ChatGPT/Codex docs/blog content are counted as Codex-side paths; shared/ and AGENT_HARNESS_DESIGN.md are counted as shared harness paths.

Scope	Commits	Changed files	Added lines	Deleted lines	What it suggests
Claude-related paths	65	150	31,982	9,809	More early design, Claude Code documentation, and rules shaped through interactive work
Codex-related paths	20	126	11,394	2,513	More Codex docs, Codex harness work, larger structure additions, and repeated cleanup
Shared harness paths	41	68	9,218	1,231	Continued work on rules, validation, and handoff material used by both AIs

The result shows a workflow where Claude Code tends to be the entry point for judgment-heavy design work, while Codex is useful after the direction is clear and the remaining work is structural or repetitive. However, model updates move quickly, and frankly, I keep adjusting the actual workflow after checking the character of each updated model. The amount of activity under shared/ is also important. In practice, separating “Claude files” from “Codex files” is not enough. Handoffs become more stable when both AIs read the same shared harness.

The Problem That Handoffs Create: Context Breaks

When switching from Claude Code to Codex, the Claude Code session context does not transfer automatically. Codex CLI can resume previous Codex sessions, but that is not the same as importing a Claude Code conversation.[3] Which files were changed, what is finished and what remains, and what reasoning led to the current state all have to be explained to Codex again.

On top of this, the longer a conversation grows, the more tokens (a unit of text that an AI model processes as input or output, affecting usage and context length) are consumed, and eventually older parts of the conversation become inaccessible. When the “context breaking” problem and the “re-explaining everything to Codex” problem overlap, the burden grows as the work becomes more complex.

Record Current State and Remaining Work in a Handoff Document

An agent-handoff (a handoff document for transferring current state and remaining work) is the note Codex reads when taking over work performed in Claude Code.

Human teams prepare handover documents when a task changes hands. I apply the same idea to sharing context from Claude Code with Codex. The document covers four items as its foundation.

Current state of work: What is currently in progress
Completed items: What was finished in the previous session
Remaining tasks: What needs to be addressed in the next session
Notes: Reasoning behind decisions, constraints, and things tried but did not work

Having this file ready means the Codex handoff can begin with: “Please read this file, then resume from where Claude Code left off.”

A Handoff Document Records Current State, Completed Work, Remaining Tasks, and Cautions

Below is the structure I use in practice.

## Current State of Work

Working on creating five new blog articles for the site.
Three Japanese versions are complete. English versions have not been started yet.

## Completed Items

- Created `claude-codex-handoff-workflow.md` (Japanese version)
- Created `japanese-ai-instruction-tips.md` (Japanese version)
- Created `feature-branch-conflict-retreat.md` (Japanese version)

## Remaining Tasks

- Create the remaining two Japanese versions
- Create all five English versions
- Run `npm run review:content` to verify

## Notes

- English articles must use `I` as the first person only — `we`, `our`, and `us` are not allowed
- `npm run build` must not run without explicit user approval

Generating the Document with `npm run agent:handoff`

In this project, a command called npm run agent:handoff generates a draft of the handoff document.

Writing the file from scratch every time is costly, so the script looks at the git change history and combines a list of modified files with recent commit messages to produce a draft. The generated file is saved to .agent-handoff/current.md, and I review and supplement it before use.

The generated file is not committed. It serves as a temporary note for passing context between sessions.

Consolidate Shared Rules Under `shared/`

Rules that both Claude Code and Codex must follow live under shared/. Claude Code enters through CLAUDE.md, while Codex enters through AGENTS.md; both files point to the same shared/rules/ sources. The entry points differ, but the policy does not need to be maintained in two places.

When I add a new rule, updating a single file under shared/rules/ reflects it for both AIs. This removes the need to explain rule differences at every handoff point.

Start a New Session When the Conversation Gets Long

Running the same task through a single long session lets conversation history accumulate and token consumption rise. When the Claude Code work reaches a natural break, I update the agent-handoff document and start the Codex session from that document.

Switching sessions takes a little time, but in my experience it tends to be more economical than continuing a long conversation. Good moments to switch are when a feature is complete, when an article is finished, or at any other natural boundary in the work.

Summary: Start a Handoff with Four Recorded Items and Shared Rules

Choosing Between Claude Code and Codex on This Site

Claude Code suits creative judgment work such as initial planning, design discussion, and investigation
Codex suits repeating implementation patterns and work that is easier to review as a larger diff or detection result, such as bulk review based on review documents
The key criteria: “does the task require judgment mid-way?” and “can I give the criteria as a document?”
This is based on the surfaces I use in this project, not on a hard product limitation
A path-based Git history review shows the same tendency: Claude-related paths lean toward design and judgment work, while Codex-related paths lean toward structural additions and repeated cleanup
Because model behavior changes with updates, I treat this as an adjustable workflow rather than a fixed division of labor
Starting with Claude to establish an approach and then handing off to Codex for repetitive work is a viable flow

Three Ways to Preserve Context Across Handoffs

agent-handoff document: record the four items (current state, completed items, remaining tasks, notes) to avoid re-explaining everything to Codex
shared/ consolidation: keep shared rules in one place to eliminate rule divergence at handoff points
Session boundaries: switch sessions at natural breaks in the work to keep token consumption manageable

The first action is to fill in only four fields for the next transfer: current state, completed work, remaining tasks, and cautions. Conversation history does not transfer between products, and model behavior changes, so the document is a reviewable restart point rather than a guarantee of automatic continuity.

References

Anthropic, Overview, Claude Code Docs
OpenAI, ChatGPT and Codex documentation, ChatGPT Learn
OpenAI, Codex CLI, ChatGPT Learn
OpenAI, Features, ChatGPT Learn
OpenAI, Codex cloud, ChatGPT Learn

For the latest releases and updates, check the official website and official documentation.