Skip to main content
Handshake is a local-first daemon that makes your AI coding sessions portable. When you hit a token limit, want to try a different model, or simply prefer a different agent for a particular task, you shouldn’t have to start over. Handshake hooks into each agent’s native event system, captures your session automatically, and generates a structured handoff brief so the next agent can pick up exactly where the last one stopped.

​
What Handshake does

Handshake runs as a background daemon on localhost:8765. It registers itself with each supported agent using the MCP protocol, which means agents treat it as a tool they can call — no manual export, no copy-pasting. Every time you checkpoint a session, Handshake reads the conversation directly from the agent’s native session storage, captures the current git state of your working directory, and stores everything locally in ~/.handshake/sessions.db. When you restore a session in a new agent, Handshake generates a handoff brief — a structured summary that gives the receiving agent the full picture: your original goal, the current state, settled decisions, and a conversation excerpt. The new agent reads the brief and continues the work as if it had been there from the start.

​
Supported agents

Handshake integrates natively with all four major AI coding agents:
  • Claude Code — reads JSONL transcript files from ~/.claude/projects/
  • OpenCode — reads from OpenCode’s SQLite database at ~/.local/share/opencode/opencode.db
  • Hermes — reads from Hermes’ SQLite state database at ~/.hermes/state.db
  • Codex — reads from the Codex session index and transcript files at ~/.codex/

​
Key features

Automatic sync

The daemon hooks into each agent’s native event system. Checkpoint by asking your agent or via the CLI — no manual export steps required.

Handoff briefs

Every restore generates a structured document: original goal, current state and next steps (written by the source agent), settled decisions, and a conversation excerpt.

Git state capture

At checkpoint, Handshake records your current branch and staged or unstaged files. On restore, it shows you exactly what has changed since the checkpoint was made.

Full-text search

Search across all session messages with search_session or search_all_sessions to find decisions, file names, error messages, or any topic discussed in a past session.

Local-first

Sessions are stored in a single SQLite file at ~/.handshake/sessions.db. Nothing leaves your machine.

Runs as a login service

Setup installs Handshake as a launchd agent (macOS) or systemd user service (Linux) so the daemon starts automatically on login.

​
Privacy

Handshake is designed to stay on your machine. The daemon binds exclusively to localhost:8765 and is not accessible from the network. There is no telemetry, no cloud sync, and no account required. Your sessions are stored entirely in ~/.handshake/sessions.db — a plain SQLite file you can inspect, back up, or delete at any time. Running handshake uninstall removes all Handshake configuration from your agents and, optionally, deletes the database and binary.
Ready to get started? Head to the Quickstart to install Handshake and make your first checkpoint in under a minute.