> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gethandshake.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Install Handshake with a single curl command or via Homebrew, run the setup wizard, and checkpoint your first session in about a minute.

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.

<Steps>
  <Step title="Install Handshake">
    Choose the installation method that works best for you.

    <CodeGroup>
      ```bash Mac / Linux (curl) theme={null}
      curl -fsSL https://gethandshake.dev/install.sh | sh
      ```

      ```bash Homebrew theme={null}
      brew install ThisisBankole/tools/handshake
      ```

      ```bash From source (requires Go 1.25+) theme={null}
      git clone https://github.com/ThisisBankole/handshake.git
      cd handshake
      go build -o handshake ./cmd/handshake
      ```
    </CodeGroup>
  </Step>

  <Step title="Run the setup wizard">
    Run the setup wizard to get Handshake ready:

    ```bash theme={null}
    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.

    <Tip>
      Setup takes about 30 seconds. Once the service is installed, Handshake starts automatically on every login — you never need to run it manually again.
    </Tip>

    <Note>
      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.
    </Note>
  </Step>

  <Step title="Make your first checkpoint">
    Inside any supported agent — Claude Code, OpenCode, Hermes, or Codex — tell it to save the session:

    ```text theme={null}
    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:

    ```bash theme={null}
    handshake list
    ```
  </Step>

  <Step title="Restore from another agent">
    Open a different agent and restore the session by name:

    ```text theme={null}
    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:

    ```bash theme={null}
    handshake restore "my session title"
    ```
  </Step>
</Steps>

You are all set. Handshake is now running in the background and ready to keep your sessions in sync across every agent you use.