Skip to main content
Restore a session when you want another agent to continue the work.

​
Prerequisites

  • The source session is in Handshake.
  • The receiving agent is connected to Handshake.
  • The project files are available when you want Handshake to compare Git state.

​
Restore in an agent

1

List the sessions

Enter:
Use the session ID when two sessions have similar titles. See List sessions.
2

Request the restore

Enter the exact ID or an unambiguous title:
3

Review the restore packet

Compare the checkpoint commit and branch with the current Git state. Review the staged, modified, added, and deleted files.
4

Confirm the restore

Tell the agent to continue. The agent calls restore_session again with confirmed: true.
5

Check the resumed context

The receiving agent states its understanding of the current state and its next action before it changes files.

​
Restore in a terminal

Run:
Handshake prints the restore packet and the handoff brief.
The command name in the current CLI is handoff. The MCP tool name is restore_session.

​
Session matching

Handshake checks candidates in this order:
  1. Exact session ID.
  2. Exact title.
  3. Title substring.
  4. Title that contains all query words.
Use the session ID if a title is ambiguous.

​
Restore without Git state

If a checkpoint has no Git state, Handshake does not show a Git drift packet. It returns the handoff brief on the first restore call.