Switching a task between Claude Code and Codex

Switching a task between Claude Code and Codex works if you treat the repository and a written handoff note as the only shared state, because nothing else carries over. The files on disk, uncommitted changes, the Git history and any notes committed to the repository are visible to both tools. The conversation, the plan the first agent was following, the commands it ran and the approaches it already ruled out stay in the first tool's own session history, which the second tool cannot read. So a switch is a handoff between two workers who have never met. Stop the first session at a clean point, write down where the task stands, and make the working tree agree with that note. Then start the second agent with a read-only pass that restates the state before it edits anything. The checklist below works in either direction. For the broader end-of-session habit, see handing off between AI sessions.

Why switch in the middle of a task

People switch for ordinary reasons. One agent has gone around the same failing test three times and a different model might see the problem differently. A usage limit was reached halfway through. You want Codex's read-only sandbox for an inspection step after Claude Code wrote the change, or the reverse. Or one tool simply handles a kind of edit better in your experience.

Before switching, check whether the agent is really the problem. If the first session is stuck because the task never said what finished looks like, the second agent inherits the same confusion plus a half-done diff. In that case stop, rewrite the work as a task an agent can finish, and then pick an agent. If the session is repeating the same fix, read why agents get stuck in a loop first; a switch can break a loop, but it can also hide the reason for it. A useful rule: switch tools to get a different view of a well-defined task, not to escape an ill-defined one.

What carries over and what does not

Carries over automatically: every file in the working tree, including uncommitted and untracked changes; the branch and its commits; anything the first agent wrote into the repository, such as notes, scripts or saved test output; and your project's configuration, lockfiles and test commands.

Does not carry over: the conversation and its reasoning; the first agent's internal plan or to-do list; which commands it ran and what they printed; approvals you granted during the session; the dead ends it tried and abandoned; and the reasons behind small decisions, such as why it kept a function signature unchanged.

Project instructions are a partial case. Claude Code reads CLAUDE.md and Codex CLI reads AGENTS.md, so rules written in one file are not automatically seen by the other tool. Keep shared rules in one place and make sure both agents are pointed at them. Permissions do not transfer either: Claude Code's permission choices and Codex CLI's sandbox and approval settings are configured separately, so decide again what the incoming agent may do rather than assuming the old session's settings apply.

A handoff checklist you can use today

Step 1: Stop at a clean point. Let the current edit finish, then tell the outgoing agent to stop making changes.

Step 2: Ask for a handoff note written to a file, not just printed in the chat: the goal, what is done, what remains, decisions made and why, files touched, checks that pass or fail, and the exact command that proves completion.

Step 3: Verify the note against the evidence. Run git status and git diff, and run the check yourself. If the note says tests pass and you have not seen them pass, treat that line as unverified.

Step 4: Checkpoint. Commit the work in progress on the task branch with the task ID in the message, so the incoming agent starts from a known state and you can roll back.

Step 5: Start the incoming agent read-only, in Claude Code's plan mode or a Codex read-only sandbox. Give it the task text and the note, and ask it to restate the current state and its next step.

Step 6: Only then grant write access, with the same scope and the same completion check as before.

Where switches go wrong

The commonest failure is an optimistic handoff note. Agents summarize their own progress generously, and a note that says the migration is done can mean the files exist but nothing has run. Step 3 above exists for this reason; see self-reported versus independent checks for the general problem.

The second failure is cleanup. The incoming agent sees half-finished code, decides it is wrong and rewrites it in its own style, undoing decisions it never knew about. Put the important decisions in the note with their reasons, and tell the new agent to continue the existing approach unless it finds a concrete defect.

The third is duplicated work. If the list of what remains is vague, the second agent redoes finished parts. Write remaining items as concrete changes with file names.

The fourth is a moving target. If you switch tools and also change the completion criteria, you can no longer tell whether the second agent did better or the bar moved. Keep the check fixed across the switch, and change one thing at a time.

QUESTIONS

Can Codex CLI continue a Claude Code conversation?

No. Each tool keeps its own session history in its own format, and neither reads the other's. What Codex can see is the repository: files, uncommitted changes, commits and any notes the first session wrote to disk. If the context matters, have the outgoing agent write it into a handoff file and check that file against the diff before the switch.

Should I commit before switching AI coding agents?

Yes, on a task branch. A work-in-progress commit with the task ID in the message gives the incoming agent a known starting point and gives you a clean rollback if the second session goes wrong. Squash the checkpoint commits later if you want a tidy history. A stash also works, but it is easier to lose track of.

How do I keep CLAUDE.md and AGENTS.md consistent?

Treat one file as the source of truth for shared rules and keep the other short, pointing to it and adding only tool-specific notes. Review both whenever a rule changes. At the start of a session after a switch, ask the agent to state the project rules it is following, which shows quickly whether it picked up the right file.

RELATED GUIDES

• Cards vs scheduled tasks: what starts an agent?
• How to read BRAIN FLUID reports and provenance

RELATED HARNESS PAGES

• How to hand off an AI coding session How to hand off an AI coding session: a short end-of-session routine so the next agent or person can continue without guessing.
• multi-agent project coordination Multi-agent project coordination: keep Claude and Codex work on one project organized with shared cards, scope, authority and review.
• Claude Code project management Claude Code project management as a workflow: run Claude from project cards, schedule tasks and review results before you accept them.
• Codex CLI project management Codex CLI project management as a workflow: launch Codex from project cards, schedule explicit tasks and inspect outcomes before accepting.