Skip to main content

​
The health check fails

  1. Run handshake serve in a terminal.
  2. Read the error message.
  3. If the port is in use, run handshake setup.
  4. Run the health check again.
Use the configured port if it is not 8765.

​
An agent cannot connect

Run:
This command writes the current MCP URL to each detected agent. Restart the agent after setup completes. Make sure that HANDSHAKE_ADDR and HANDSHAKE_URL use the same port.

​
A session is not in the list

Import native sessions:
You can limit the import to one agent:
Then list the sessions again.

​
The list contains a synchronization warning

The warning identifies the agent storage that Handshake could not read. Check that the storage exists and that your account can read it. A partial import does not remove sessions that Handshake imported successfully.

​
Claude Code hooks do not run

Make sure that Python 3 is on PATH. Then run:
Handshake can still use MCP tools when the automatic hooks are not available.

​
Project knowledge remains stale

Check the writer:
If no writer is selected, configure one: