How to hand off work in Claude Code

Updated Oct 10, 2026·3 min read

The short answer

Hand off work between Claude Code sessions, or from Claude Code to Codex or Cursor, with a short file instead of a transcript. It says what's done, what's next, what was tried and dropped, and what was decided. The next agent reads it with the job plan and picks up where the last one stopped, without a recap from you.

Why transcripts make bad handoffs

A long session is mostly dead ends, half-finished thoughts and output you don't need. Pasting it into the next agent buries the five lines that matter, and uses up the context the next agent needs for the work.

What a good handoff contains

The goal. One line, linked to the job plan.
Done so far. What changed, with the branch or files.
Tried and dropped. Each approach that didn't work, with the reason. This stops the next agent trying it again.
Decided. Any answer you gave along the way.
Test state. What passes, what fails, what wasn't run.
Next step. The exact next action, in one sentence.

Where to keep it

In the branch, as a file. Commit a HANDOFF.md with the work, so it's on GitHub next to the code it describes. The next agent pulls the branch and reads it first.
In the pull request. Put the same summary in the PR description. A reviewer reads it there, and so does the next agent when it opens the PR.

Either way it lives with the work, not in a chat that disappears.

When to write one

Before a session gets long enough to compact.
When you hit a usage limit and switch tools, say from Claude Code to Codex.
When one agent writes and another reviews.
When you stop for the day.

Using Claude Code and Codex (or Cursor) together

Give each tool a different job from the same list, or split one job into writing and reviewing. Both read the same project file and the same job plan. The handoff file is how work crosses between them, so neither needs the other's chat.

Copy this

Save this as a file in the branch, and have the next session read it first.

A handoff file the next agent reads first

# Handoff: <job title>
Plan: <link to the job plan>
Branch: <branch>

## Done
- <change>

## Tried and dropped
- <approach>: <why it didn't work>

## Decided
- <decision> (<who>, <date>)

## Tests
- Passing: <...>  Failing: <...>  Not run: <...>

## Next step
<one sentence>

Where Annsa fits

In Annsa a handoff is a note on the job: the agent hands over with what it tried, and the next agent, in any tool, reads it with the spec over MCP. One agent holds the job at a time, so two don't pick up the same work. Claim, hand off and ship

See how it fits together in Direct your agents.

Questions people ask.

How do I hand off a task in Claude Code?

Ask it to write a short handoff file before it stops: done, tried and dropped, decided, test state and the next step. Start the next session by reading that file and the job plan.

What should a handoff to another agent contain?

The goal, what's done, what was tried and dropped with reasons, any decisions, the test state and the exact next action.

Can Claude Code and Codex work together?

Yes. Give them different jobs, or have one write and one review. They share the project file and job plan, and pass work with a handoff file.

How do I switch from Claude Code to Codex mid-task?

Have Claude Code write the handoff file, commit the branch, then start Codex on the same branch with the handoff and the plan.

Get your agents in a row.

Try Annsa