Skip to content
AI Learning Playground
LinkedInX
English
English

Handing Work from Claude Code to Codex: Designing and Using an agent-handoff Document

Shiori
Shiori

What This Article Covers

When I move work from Claude Code to Codex, I may need to explain from the beginning how far the task has progressed. This article describes the agent-handoff document I designed to transfer that context from Claude Code to Codex, including what to put in it and how I use it.

The Starting Point: Fatigue from Explaining Everything Again

At one point, I was working with AI on adjustments to the site’s navigation structure. After spending several hours clarifying the problem, settling on an approach, and modifying several files, I finished for the day.

The next day, when I asked Codex to continue, I realized that the context from the previous day’s Claude Code session had not transferred automatically. Which files had been changed, what was finished and what remained, and what reasoning led to the current state all had to be explained from scratch.

The burden of this “start-from-scratch” situation grows as the work becomes more complex.

What an agent-handoff Document Is

An agent-handoff document is a handover note that 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.

  1. Current state of work: What is currently in progress
  2. Completed items: What was finished in the previous session
  3. Remaining tasks: What needs to be addressed in the next session
  4. 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.” That single line replaces a lengthy re-explanation.

A Concrete Example

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 `agent-handoff-documentation.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

How npm run agent:handoff Generates the Document

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.

The Actual Effect

Since I started using handoff documents, the explanation required when moving from Claude Code to Codex has decreased. A handoff that used to begin with a detailed account of what Claude Code had completed now begins with “Please check .agent-handoff/current.md and continue from there.”

Whether AI can resume with the right context depends on the quality of the document. If the line between “completed” and “remaining” is blurry, or if the notes are too vague, the handoff loses its value. My early attempts were rough, but after using the format several times, I developed a clearer sense of what information AI actually needs.

Summary

  • Context from a Claude Code session does not transfer to Codex automatically
  • An agent-handoff document functions as the handover note Codex reads before starting
  • The four items to include are: current state, completed items, remaining tasks, and notes
  • npm run agent:handoff generates a draft that I review and supplement before use
  • The quality of the document determines the accuracy of the handoff, so it improves with iteration
Tags: