Handing work to the next session
A coding session often ends before the work does. The next session, yours tomorrow or a colleague’s, starts without the conversation. In this lesson we end a session with a handoff file and measure what it saves: the number of turns a fresh session needs before it does useful work, first from the diff alone and then from the handoff.
The lesson uses Claude Code, and the files are in the course repository at
site/examples/customizing-agents/session-handoff/. session.md is the log
of a session that stopped halfway, written for this lesson.
setup_practice.py builds a practice repository in the state that session
left behind, and check_handoff.py checks a handoff file. Both are short
Python scripts. The first builds its repository in a new directory that
you name, and the second only reads the file you give it. Run the commands
in this lesson from that directory. In the cd line, replace
<course-repo> with the path to your copy of the course repository.
cd <course-repo>/site/examples/customizing-agents/session-handoffWhat the next session starts from
Section titled “What the next session starts from”In Claude Code, a new session doesn’t see the conversation of an earlier
one, and its context window starts empty [1].
At its start it loads CLAUDE.md and the auto-memory notes
[2]. Everything else it learns from the repository, and
that includes the changes that aren’t committed yet.
The Agent Engineer Course separates a session from its state. The session is the full history of messages, tool calls and results. The state is a short summary of the facts that matter, which is quicker to use than the history [3]. A session handoff is that state, written to a file before the session ends: what was done, what is left, what was decided and why, what was tried and ruled out, and where the files are. The next session reads the file and starts from it.
Claude Code can also reopen an old conversation. claude --continue
opens your last conversation in this directory again, and
claude --resume shows the saved conversations so that you can pick one
[4]. That helps when you continue the same work
on the same computer, because Claude Code keeps the conversations as files
on your own computer, in ~/.claude/projects/ [1].
A colleague on another machine can’t resume them. A resumed conversation also
brings back its whole history, and that includes the approaches that went
wrong. The best-practices page gives advice for the case where you have
corrected the agent more than twice on the same problem: clear the
conversation, and start again with a prompt that states what the failed
attempts taught you [4]. A handoff file is that
prompt, written down before the session ends.
What does the new session know?
Section titled “What does the new session know?”In Claude Code, a session ended yesterday with work left to do. During it the user ruled out an approach in the chat. Auto-memory is turned off. Today a new session starts in the same repository, without --continue or --resume.
Yesterday’s session ended before the work was done, and nobody wrote anything down. What does today’s new session have to go on?
Which of these is in a file that the new session reads, and which exists only in yesterday's conversation?
Start from the diff alone
Section titled “Start from the diff alone”Read session.md first. In it a user and an agent work on a bug in a small
report service: the export writes a report created at midnight on 1 March
in Auckland as 11:00 on 28 February. The agent first changes the test to
expect the wrong time. The user rules that out, and then rules out the
server’s time zone too. Three decisions follow, each with a reason. The
session stops before any code is changed, and the edit to the test is
still there.
Build two practice repositories from the same state, one for this section and one for the rest of the lesson. The script refuses a directory that already exists.
python3 setup_practice.py ~/handoff-diff-onlypython3 setup_practice.py ~/handoff-practiceHere is what a fresh session finds in either of them: the output of
git status --short, git diff --stat=60 and the tests.
Look at the practice repository
Section titled “Look at the practice repository”Run these in ~/handoff-diff-only, and compare with the output below. The
last line is the verdict of python3 -m unittest -q, which prints
Ran 4 tests and then OK in your terminal.
git status --shortgit diff --stat=60python3 -m unittest -qM test_reports.py test_reports.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) tests: OK
Output verified in CI from site/examples/customizing-agents/session-handoff/diff_only.py.
The repository shows one changed line in a test and a green suite. It
doesn’t show that the change was ruled out, or why, or what the fix
should look like. Now let a fresh session work from that. Start Claude
Code in ~/handoff-diff-only with two settings. The environment variable
CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 turns auto-memory off
[2], so no memory note can carry facts from one practice
session to the next. --permission-mode default starts Manual mode, where
the agent may read files without a prompt and asks before edits and
commands [5], so you see the steps it wants
to take.
cd ~/handoff-diff-onlyCLAUDE_CODE_DISABLE_AUTO_MEMORY=1 claude --permission-mode defaultType this as your first message:
Continue the work in progress in this repository.Count your turns: each message you type is one, and the first message
counts. Useful work has started when the agent undoes the edit to the
test, or starts to change format_ts() so that each time keeps its own
offset. If the agent asks a question, answer it from session.md, and
count the answer. Stop after five turns if useful work hasn’t started, and
write down “more than 5”. Then leave with /exit and write down your
count. A model answers differently each time, so your count may differ
from a colleague’s.
The fresh session says it is done
Section titled “The fresh session says it is done”A new Claude Code session starts in a repository where yesterday's session left one uncommitted edit: a test's expected value changed to match the code. The user ruled that edit out in yesterday's chat, and nothing was written down.
The fresh session answers: “The expected value in test_export_timezone
was updated to match the UTC output, and all 4 tests pass. Shall I commit
the change?” What do you do?
Where is the reason that the edit is wrong, and what does the agent need so that the next session doesn't ask again?
Write the handoff before the session ends
Section titled “Write the handoff before the session ends”A handoff is written by the session that did the work, before it ends. In
this lesson that session is the one in session.md, so you replay it and
then ask for the handoff. Start Claude Code in ~/handoff-practice with
the same two settings.
cd ~/handoff-practiceCLAUDE_CODE_DISABLE_AUTO_MEMORY=1 claude --permission-mode defaultOpen session.md in an editor, copy from the first **User:** line to
the end, and paste it as your first message. If the agent asks to edit a
file, answer no. Then ask for the handoff:
Write HANDOFF.md for the next session on this work. Name the current state and the next step, every decision with its reason, the failing test, what was tried and ruled out and why, and the files to look at. Use only this conversation and the repository, and change no other file.Approve the edit that writes HANDOFF.md, and leave with /exit. If
Claude Code prints a message that says it saved memories, auto-memory is
still on [2]. Then build a new practice repository with
another name and start again.
Check the file from the course directory:
cd <course-repo>/site/examples/customizing-agents/session-handoffpython3 check_handoff.py ~/handoff-practice/HANDOFF.mdThe script looks for the words that name each fact the next session needs
and prints named or missing. It only matches words, so open the file
and read it before you trust a missing, and a named only means that the
words are there. The course repository has two
handoffs written for the lesson, and no model produced them.
samples/files-only.md lists the changed file and the files to read, and
it has no decisions.
Check the handoff that lists files
Section titled “Check the handoff that lists files”Run this, and compare with the output below.
python3 check_handoff.py samples/files-only.mdsamples/files-only.md state, undo the edit to test_reports.py: missing decision, keep each offset, for customers: missing decision, UTC stays Z, for billing: missing decision, no offset means UTC: missing failing test, test_export_timezone: missing ruled out, the server's time zone: missing where the fix goes, format_ts(): named named 1 of 7
Output verified in CI from site/examples/customizing-agents/session-handoff/files_only.py.
A fresh session that reads this file learns where to look and still
repeats the test edit. samples/full.md has a section for the state,
the decisions with their reasons, what was ruled out, and the next steps
in order.
Check the full handoff
Section titled “Check the full handoff”Run this, and compare with the output below.
python3 check_handoff.py samples/full.mdsamples/full.md state, undo the edit to test_reports.py: named decision, keep each offset, for customers: named decision, UTC stays Z, for billing: named decision, no offset means UTC: named failing test, test_export_timezone: named ruled out, the server's time zone: named where the fix goes, format_ts(): named named 7 of 7
Output verified in CI from site/examples/customizing-agents/session-handoff/full.py.
If your HANDOFF.md misses a fact that is really gone, add it by hand.
The handoff is yours to correct before the next session reads it.
Which lines belong in the handoff?
Section titled “Which lines belong in the handoff?”A session on a time zone bug ends before the fix. The user ruled out one approach in the chat and made a decision with a reason. The agent is about to write HANDOFF.md for the next session.
Which two lines tell the next session something it can’t find in the repository?
Which of these can the next session not find in the code, the tests or the diff?
Start fresh from the handoff
Section titled “Start fresh from the handoff”Now start a new session in ~/handoff-practice, with the same two
settings as before:
cd ~/handoff-practiceCLAUDE_CODE_DISABLE_AUTO_MEMORY=1 claude --permission-mode defaultThen type:
Read HANDOFF.md and continue the work.Count the turns until useful work starts, by the same rule as before, and
leave with /exit. Compare the two counts. With a handoff that names the
ruled-out edit, the agent can start on the next step in its first answer.
Without it, the agent may commit the wrong test, or you spend turns
telling it what the log says. One pair of counts says little on its own,
because a model answers differently each time. The handoff changes what
the agent knows at its first turn, and that holds on every run.
The handoff is for this piece of work, and it goes where the work is. Keep
HANDOFF.md on the branch until the work is done, and delete it with the
last commit. A fact that outlives the work belongs somewhere else. A
decision with lasting reasons, such as the Z form for the billing
import, goes in a decision file, as
Keep the reasons where the agent reads them
described. A rule that every session needs goes in the project-root
CLAUDE.md, which each session loads at its start [2].
Can the next session see it?
Section titled “Can the next session see it?”A session on a time zone bug in a report service ended before the fix, with one uncommitted edit to a test. A new session starts in the same repository tomorrow, without the old conversation.
Can git status, git diff or a test run show this, or was it only said in the chat?
Where does each fact go?
Section titled “Where does each fact go?”A developer ends a Claude Code session on a bug fix that continues tomorrow. Each row is a piece of information from the session, and the options are places to put it.
Match each piece of information to where it goes before the session ends.
Is the fact needed for this piece of work only, for every session on the project, or can the next session see it anyway?
A colleague takes over
Section titled “A colleague takes over”A developer's Claude Code session on a bug is halfway done and has ruled out two approaches in the chat. A colleague takes the work over tomorrow on their own computer, while the developer is away.
You leave tomorrow, and a colleague continues the bug on their own computer. What do you do before you close the session?
Which of these can the colleague's own session read tomorrow, on another computer?
Exercise
If you followed the steps above, you have the exercise: your
HANDOFF.md, its result from check_handoff.py, and two counts. Otherwise
do the steps now: build two practice repositories, count the turns of a
fresh session in the first, replay session.md in the second and have
the agent write HANDOFF.md, and count the turns of a fresh session that
starts from it. The agent works in copies that the script built, and in
Manual mode it asks before edits. The steps take about fifteen minutes
and show you what a handoff saves in turns.
A good result: HANDOFF.md names the ruled-out test edit, the server’s
time zone, the three decisions with their reasons and the failing test,
and the fresh session starts useful work in its first turn or second
turn. The count without a handoff is higher, or the agent went wrong
where you didn’t correct it. If the fresh session found the fix from the
code alone, ask it which decisions it followed and why. It can’t name the
billing import or the database team, and those reasons are what the
handoff adds. When you are done, delete the practice directories you
built. In your own last session that stopped halfway, what did you
rule out that no file shows?
Stretch: Write a second handoff by hand for the same session, from the log alone and without the agent. Start a new practice repository from it and compare its count with the first.
Recap
- A new Claude Code session starts without the old conversation. It
loads
CLAUDE.mdand auto-memory and reads the rest from the repository [1] [2]. - A session handoff is the state of the work written to a file before the session ends: what is done, what is left, the decisions with their reasons, what was ruled out, and where the files are [3].
- The diff shows what changed. The reasons and the rejected approaches are only in the conversation, so they are what the handoff must hold.
- Resuming works on your own machine, and it brings back the approaches that went wrong too. A handoff works for any session and for a colleague [1] [4].
- Keep the handoff with the work and delete it when the work is done. Move
a lasting decision to a decision file and a rule for every session to
CLAUDE.md.
You can now
- Manages what the agent carries between sessions
References
Section titled “References”- Anthropic. How Claude Code works. Claude Code documentation. Reference.
Claude Code how it works - Anthropic. How Claude remembers your project. Claude Code documentation. Reference.
Claude Code memory - Addy Osmani, Ivar Soares Urdalen, Leo Simons. Memory and context: context engineering, memory kinds, memory versus RAG, context rot. Agent Engineer Course. Course.
AEC-05 - Anthropic. Best practices for Claude Code. Claude Code documentation. Reference.
Claude Code best practices - Anthropic. Choose a permission mode. Claude Code documentation. Reference.
Claude Code permission modes