Skip to main content
Handshake uses one local daemon and one SQLite database. Agent integrations write session data to the daemon or tell the daemon to read native storage.

​
Daemon interfaces

The daemon listens on localhost:8765 by default. It refuses a non-loopback address. The server rejects browser requests that have a non-loopback origin. It also limits request bodies to 32 MiB.

​
Session synchronization

Handshake gets sessions in two ways.

​
Agent push

Hooks, plugins, and MCP tools send a session to Handshake. Handshake reads the native session when the integration supplies a native session ID.

​
Handshake pull

Handshake reads supported native agent storage. A pull imports a new session or a newer native copy. It does not replace a stored summary or decision. Handshake starts a catch-up pull when the daemon starts. You can also run:

​
Checkpoint data

For a Git-aware session, Handshake records:
  • The current branch.
  • Staged and unstaged file state.
  • The Git remote.
  • Commits that apply to the session.
  • A project identity and factual project revision.
Handshake stores session data in ~/.handshake/sessions.db. It stores project knowledge in ~/.handshake/knowledge/<project-id>/.

​
Restore sequence

1

Find the session

Handshake matches an exact ID or an unambiguous title.
2

Compare the Git state

The first restore call returns a restore packet when the checkpoint has Git state. The packet shows drift between the checkpoint and the current working directory.
3

Confirm the restore

The second restore call uses confirmed: true.
4

Load the context

Handshake creates the handoff brief and adds current project knowledge when it is available.

​
Handoff brief

The handoff brief can contain:
  • The original goal.
  • The source agent and working directory.
  • The current state and next actions.
  • Settled decisions.
  • A full or sampled conversation.
  • Current project knowledge.
Handshake includes all substantive messages when there are 50 or fewer. For a longer session, it selects 50 messages from the start, middle, and end.

​
MCP tools

Handshake provides nine MCP tools. These tools checkpoint, list, restore, preview, and search sessions. They also report update status and manage project knowledge. See the MCP tools reference.