Choosing Between Claude Code and Codex, and Recording Work for Handoffs
What you’ll learn
- The order for confirming work scope and verification results before a handoff
- How to record current work, completed items, remaining tasks, and cautions in a handoff document
- How shared rules and natural breaks between sessions keep the same assumptions available when switching AI tools
A Record That Preserves Working Assumptions Across AI Tools
When handing work from Claude Code to Codex, the conversation does not transfer automatically. The next AI needs a written record of the current state, completed work, remaining tasks, and cautions to resume with the same decision criteria. If the scope and verification results are unclear, it may proceed with different assumptions.
On this site, I use Claude Code and Codex in the same repository—a place for managing code, documents, and their change history. I choose between them according to the type of work and sometimes switch tools partway through a task.
This article explains why context can be lost during a handoff and how to record the state before switching and confirm it in the next session. Combining handoff documents, shared rules, and natural breaks in the work reduces repeated explanation while keeping the state of the work available for a person to review.
Tool selection is covered in Choosing Between Claude Code and Codex. This article focuses on recording and resuming work after that decision.
Recording the State Before Switching and Resuming Work
Before switching, establish what the next AI may do and what still needs checking. The aim is to preserve the state needed to resume work.
- Check which files changed and which tasks are complete
- Record the checks run, their results, and checks that have not been run
- Write remaining tasks, decision reasons, and boundaries on changes in the handoff document
- Ask the next AI to read the handoff document and shared rules before resuming
- Check that its understanding of the current state and first task matches the record
Even after choosing the tool, marking work that awaits verification as complete can cause the next AI to skip checks. Record completed and unverified work separately.
A Handoff Example: From Japanese and English Article Creation to Verification
On this site, I created Japanese and English articles with Claude Code and used Codex for article verification and related checks. This is an example of switching tools between creating articles and checking the completed work.
A record for that handoff separates the Japanese and English articles to check, what has already been verified, and what remains unchecked. It lets the next AI read the completed articles and check their correspondence and validation results. This describes how I used the tools on this site; it does not limit the work either product can perform.
Conversation Context Lost When Switching AI Tools
Switching from Claude Code to Codex does not automatically transfer the Claude Code session—a continuous stretch of work or conversation. Codex CLI can resume previous Codex sessions, but that feature does not import Claude Code conversation history.[1]
I therefore need to tell Codex which files changed, what is complete, what remains, and the reasoning that led to the current state.
Context is also an issue when a long conversation continues with the same AI. As the conversation grows, the AI processes more tokens. Tokens are units of text and other data used to process input and output; they relate to usage and the amount of context the AI can handle. As a conversation becomes longer, older content becomes unavailable.
When lost context is combined with explaining the work again at every handoff, complex tasks become more burdensome. On this site, I address this with three methods: handoff documents, shared rules, and breaks between sessions.
Four Items to Record in a Handoff Document
On this site, I call the note Codex reads first when taking over a task an “agent-handoff.” It is a document for sharing the current state and remaining tasks.
I apply the same idea as a handover document used when a person takes over work from a teammate. The foundation is these four items:
| Item | What to record |
|---|---|
| Current state of work | What is in progress now |
| Completed work | What finished during the previous session |
| Remaining tasks | What needs attention in the next session |
| Cautions | Reasons behind decisions, constraints, and approaches tried that did not work |
With a concise file covering these items, I can begin a handoff with “Please read this file before resuming work.” I also record the scope and verification results within these four items so the next AI can understand them.
An Example Handoff Document
The following is an example structure for a handoff document in this project. Conditions for running commands and writing conventions are recorded as cautions too.
## 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 Work
- 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
## Cautions
- English articles must use `I` as the first person only (`we` / `our` / `us` are prohibited)
- Do not run `npm run build` without explicit user approvalGenerating a Draft with npm run agent:handoff
This project includes a way to generate a handoff template with npm run agent:handoff. I prepared it to reduce the effort of writing the document from scratch every time.
The script reads the Git state and produces a draft with a list of changed files, a summary of the diff, and information about the current branch and commit. The generated file is saved to .agent-handoff/current.md. The person doing the work reviews it and adds any explanation needed before using it.
This file is not committed. It is treated as a temporary note for passing work between sessions.
Shared Rules Both AIs Read
The rules Claude Code and Codex share are collected under shared/. Claude Code starts with CLAUDE.md, and Codex starts with AGENTS.md; both entry points lead to the same shared/rules/ directory.
Although the initial instruction files differ, the shared policy does not need to be maintained twice. To add a rule, I update the relevant file under shared/rules/ so both AIs can read it. This also reduces the need to explain differences between tool-specific rules at every handoff.
Switching Sessions at Natural Breaks in the Work
Working through a single long session accumulates conversation history and increases token usage. On this site, I update the handoff document when Claude Code reaches a break in the work, then start a Codex session from that document.
Switching also takes time to update and check the document. I have not measured the cost difference against continuing the conversation, so I do not claim cost savings from switching. I choose natural breaks, such as completing a feature or an article, as points to switch.
Summary: Record the Handoff at a Natural Break
The core of a handoff is to separate completed and unverified work and preserve a record that lets the next AI resume with the same assumptions. Treating tool selection and the subsequent handoff procedure as separate decisions makes missing checks easier to identify.
For a handoff, I document the current state, completed work, remaining tasks, and cautions, and make shared rules available to both AIs. Updating that document at a natural break and keeping it reviewable by a person creates a record the next AI can use to resume with the same assumptions.
References
- OpenAI, Codex CLI, ChatGPT Learn
For the latest releases and updates, check the official website and official documentation.