Skip to main content
Handshake installs as a single binary and configures itself automatically. By the end of this guide you will have a running daemon, your agents registered, and your first session checkpointed — all in about a minute.
1

Install Handshake

Choose the installation method that works best for you.
curl -fsSL https://gethandshake.dev/install.sh | sh
2

Run the setup wizard

Run the setup wizard to get Handshake ready:
handshake setup
The wizard walks you through three steps:
  1. Create the database — initialises ~/.handshake/sessions.db and registers Handshake with each agent on your machine (Claude Code, OpenCode, Hermes, and Codex).
  2. Install as a background service — installs Handshake as a launchd agent (macOS) or systemd user service (Linux) so the daemon starts automatically every time you log in.
  3. Start the daemon — starts Handshake immediately so you don’t have to log out first. If the service was installed, the daemon is already running and this step just verifies it.
Setup takes about 30 seconds. Once the service is installed, Handshake starts automatically on every login — you never need to run it manually again.
Handshake defaults to localhost:8765. If that port is already in use, setup detects the conflict automatically, picks the next free port, and registers all agents with the new address. No manual action needed.
3

Make your first checkpoint

Inside any supported agent — Claude Code, OpenCode, Hermes, or Codex — tell it to save the session:
checkpoint this session
Handshake reads the full conversation from the agent’s native storage, captures your current git branch and file changes, and stores everything locally.You can also see your checkpointed sessions from the terminal at any time:
handshake list
4

Restore from another agent

Open a different agent and restore the session by name:
restore my <session name> session
The agent receives a full handoff brief — your original goal, current state, settled decisions, and a conversation excerpt — and continues the work from where the previous agent stopped.You can also restore from the CLI:
handshake restore "my session title"
You are all set. Handshake is now running in the background and ready to keep your sessions in sync across every agent you use.