Codex and Claude Code Task Handoff Guide: From Implementation and Review to Long-Task Recovery

The easiest mistake in a Codex and Claude Code handoff is treating it as “two AIs writing code together.” The stable version is almost the opposite: during each phase, one tool writes while the other reviews, summarizes, restores context, or takes the next stage.

If Claude Code and Codex edit the same files at the same time, it may look fast at first, but the later cost is high. You no longer know who changed what, which edit introduced a failing test, or whether one Agent overwrote the other’s design. The point of handoff is not parallel coding. It is splitting a complex task into phases so each tool can work where it is strongest.

Quick Answer

Start with this division of labor:

The core rules are simple:

1. Only one Agent writes code at a time.
2. Create a handoff packet before every transfer.
3. The receiving Agent reviews state first instead of editing immediately.

When Handoff Is Worth It

Not every task needs two tools. Handoff is useful when:

• Claude Code has implemented something and Codex should review it independently;
• Codex produced a plan or findings and Claude Code should apply them;
• a long task was interrupted and another Agent needs to continue from a checkpoint;
• local and cloud environments need different roles;
• one tool owns the current session while the other is better for pre-PR review;
• you want a second view to challenge a design.

For a one-line config change or a typo, handoff adds more overhead than value. The cost is that you must describe state, boundaries, and the next action.

Do Not Let Two Agents Write the Same Files

This is the most important safety rule.

Not recommended:

1
2

Claude Code continues the login refactor.
Codex optimizes the same login files at the same time.

Recommended:

1
2
3

Claude Code implements the login refactor. When done, it stops and outputs a handoff packet.
Codex reviews the diff in read-only mode and does not modify files.
Claude Code fixes the Codex findings.

That keeps responsibility clear. If something breaks, you know which phase introduced it.

What a Handoff Packet Should Include

Every transfer from Claude Code to Codex, or from Codex to Claude Code, should include a short packet:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

## Agent Handoff

### Original Goal
-

### Current Phase
- Plan / Implementation / Test / Review / Fix / Pre-release check

### Done
-

### Pending
-

### Changed Files
-

### Verification Run
-

### Current Risks
-

### Do Not Repeat
-

### Suggested Next Step
-

This is not a pretty summary for humans. It is a recovery record for the next Agent. It must contain files, verification, and boundaries.

This pairs well with how to resume interrupted AI Agent long tasks. A handoff is a deliberate form of recovery.

Claude Code to Codex: Review After Implementation

This is the most common and stable pattern:

1. Claude Code finishes the implementation.
2. Claude Code runs the smallest relevant tests.
3. Claude Code outputs a handoff packet.
4. Codex reads the diff and performs read-only review.
5. Claude Code fixes the findings.
6. Codex re-reviews.

Prompt for Claude Code:

1
2
3

Please implement this feature, but do not commit.
Before stopping, output a handoff packet with changed files, tests run, pending items, and risks.
Do not expand the scope before another Agent reviews it.

Prompt for Codex:

1
2
3

Please review the current uncommitted changes in read-only mode. Do not modify files.
Focus on bugs, regression risk, security issues, edge cases, and missing tests.
List findings by severity and reference exact file locations.

Codex CLI documentation also treats review as a separate capability: it can review uncommitted changes, a commit, or a diff against a base branch and return prioritized findings. Keep this stage read-only.

Codex to Claude Code: Fixing Review Findings

After Codex returns findings, do not automatically let the reviewer rewrite everything. A safer pattern is to hand the findings back to Claude Code, especially when Claude Code already owns the implementation context.

Prompt for Claude Code:

1
2
3
4
5
6
7

Below are Codex review findings. Handle them one by one.

Constraints:
1. Fix only the issues referenced by the findings.
2. Do not do extra refactoring.
3. Run the smallest relevant test after each class of fix.
4. When done, report handled / not handled / needs human judgment.

This prevents the common “review feedback arrived, so the Agent rewrote the whole module” problem.

Codex to Claude Code: Plan Handoff

Sometimes Codex is better used first for codebase reading, planning, or risk assessment, while Claude Code performs the edits.

Good cases:

• the repository is unfamiliar;
• the change is broad and needs milestones;
• you want Codex to plan without touching files;
• Claude Code is better positioned in the local IDE or terminal.

Prompt for Codex:

1
2
3
4
5
6
7
8

Please only plan; do not modify files.
After reading the relevant code, output:
1. goal understanding;
2. impact area;
3. suggested files to change;
4. phased implementation plan;
5. verification for each phase;
6. risks and rollback strategy.

Then give Claude Code only the first phase:

1
2
3

Please execute only phase 1 from this plan.
Do not start phase 2 early.
Run the matching verification and output a handoff packet when done.

The larger the handoff, the more important it is to avoid doing everything at once.

Long-Task Transfer

If a Claude Code session has accumulated lots of context, but the task is becoming long or needs independent review, do a manual transfer.

Ask Claude Code:

1
2
3
4
5
6

Please turn the current task into a handoff packet for Codex.
Requirements:
1. Under 800 words.
2. Include goal, done, pending, changed files, verification, and risks.
3. State Codex's first step after receiving it.
4. Mark commands that should not be repeated.

Then ask Codex:

1
2
3

Below is a Claude Code handoff packet. First review it; do not modify files yet.
Check current git status and diff, verify the packet matches the workspace,
then execute only the stated first step.

This is much more reliable than saying “continue what Claude Code was doing.”

If you use a bridge such as codex-plugin-cc, see codex-plugin-cc: connecting Codex to Claude Code workflows. Even without a plugin, a manual handoff packet is enough for most tasks.

Be Careful With Resume

Codex CLI has codex resume. Claude Code also has --resume, --continue, or session recovery entry points. In both ecosystems, resume means returning to an existing session.

But resume is not a magic safety net. Before relying on it, ask:

1. Is this session for the current repository?
2. Does the workspace state match the session memory?
3. Did the previous run already execute side-effecting commands?

A safer first prompt after resume:

1
2
3

We are resuming an old session. Do not edit files yet.
Please inspect the current workspace state and compare it with your remembered task state.
If they differ, trust the current workspace and output a recovery summary first.

That avoids applying stale plans to newer files.

Use Git as the Boundary

Git is the best handoff line:

1
2
3

git status --short
git diff --stat
git diff

If a phase is done, consider making a small commit:

1
2

git add <files>
git commit -m "feat: implement login validation"

Then the other Agent can review that commit or the diff against the base branch.

If you do not want to commit, save a patch:

1

git diff > handoff-login-validation.diff

Do not hand off in a messy workspace. At least separate user changes, Claude Code changes, Codex changes, and files the next Agent must not overwrite.

Use Hooks to Make Handoff Habits Stick

If you hand off often, write “output a handoff packet before stopping” into Claude Code hooks or project rules.

For handoff, hooks do not need to switch tools automatically. The useful part is reminding the Agent to record state:

1
2
3
4
5

If this turn changed files, output:
- changed files;
- verification run;
- pending items;
- suggested next step for Codex.

On the Codex side, the same flow can become a skill. See how to write your own Codex Skills workflow and split the process into read-only review, handoff parsing, and long-task recovery.

Local, IDE, and Cloud Roles

Do not force every task into one window.

The point is not which tool replaces the other. The point is clearer context and responsibility boundaries.

A Complete Handoff Example

Task: refactor user import and add tests.

Step 1: Claude Code Implements

1
2
3

Refactor the user import flow. Only handle CSV parsing and field validation.
Do not change UI or database schema.
Run the relevant unit tests and output a handoff packet.

Step 2: Codex Reviews Read-Only

1
2
3
4
5
6

Review the current uncommitted diff. Do not modify files.
Focus on:
1. CSV edge cases;
2. error handling;
3. types and null values;
4. whether tests cover failure paths.

Step 3: Claude Code Fixes Findings

1
2
3

Fix only the P1/P2 issues from the Codex findings.
Do not do extra refactoring.
Run the related test after each fix.

Step 4: Codex Re-Reviews

1
2

Re-review the current diff and confirm whether the previous findings are resolved.
If there are no new high-confidence issues, state the remaining risks clearly.

Step 5: Human Decides the Commit

AI can assist, but the final decision to commit, merge, or release should remain human.

Common Mistakes

Two Agents Editing Each Other’s Code

Use the single-writer rule: one writes, one reviews.

Handoff Packet Too Long

A handoff packet is not a chat transcript. Keep it short, structured, and actionable.

No Verification

“Feature complete” is not enough. State what was run, what was not run, and what failed.

Reviewer Also Fixes Everything

Keep review and fix separate. Review read-only first, then let the implementer handle fixes.

Stale Context

After resuming an old session, align it with the current workspace before editing.

Treating Handoff as a Fully Automatic Pipeline

Do not chase full automation first. Stabilize handoff packets, read-only review, and fix-by-findings before adding hooks or skills.

Handoff Checklist

If you cannot fill this table, do not hand off yet.

References

• OpenAI Developers: Codex CLI features: https://developers.openai.com/codex/cli/features
• OpenAI Developers: Codex workflows: https://developers.openai.com/codex/workflows
• OpenAI Developers: Codex IDE extension features: https://developers.openai.com/codex/ide/features
• Anthropic Docs: Claude Code common workflows: https://docs.anthropic.com/en/docs/claude-code/common-workflows
• Anthropic Docs: Claude Code hooks guide: https://docs.anthropic.com/en/docs/claude-code/hooks-guide

Summary

The key to Codex and Claude Code handoff is not making two Agents work at the same time. It is making them collaborate in phases.

Claude Code can own implementation, fixes, and local continuous work. Codex can own independent review, plan review, pre-PR checks, and long-task continuation. Every transfer should use a structured handoff packet with the goal, changed files, verification, risks, and next step. Git, resume, review, hooks, skills, and checkpoints provide the boundary.

Once “one writes, one reviews, and the receiver reviews state first” becomes a habit, handoff turns from chaotic dual-AI work into a controlled engineering process.