Skip to main content
Uninstalling Handshake removes it from all agent configurations, stops the background daemon, and optionally deletes the session database and the binary. The process takes about ten seconds and guides you through each decision with prompts.

​
Uninstall Command

Run the following from any terminal: 
handshake uninstall
The command performs these steps in order:
1

Stop the daemon

Stops any running handshake serve process and removes the login service (launchd on macOS, systemd on Linux).
2

Deregister from all agents

Removes the Handshake MCP entry from Claude Code, OpenCode, Hermes, and Codex configuration files.
3

Prompt to delete session history

Asks whether to delete the ~/.handshake directory and everything in it. Your session history is preserved if you answer no.
Delete session database? Your session history will be lost. [y/N]
4

Prompt to remove the binary

Asks whether to remove the handshake binary from your machine.
Remove the handshake binary from your machine? [y/N]

​
Keep Your Session History

If you answer no to deleting the database, your sessions remain at ~/.handshake/sessions.db. Reinstall Handshake at any time and your full session history will be there waiting: 
# Reinstall
brew install ThisisBankole/tools/handshake
handshake setup
Handshake detects the existing database and picks up where you left off.

​
Homebrew Uninstall

If you installed Handshake via Homebrew, the uninstall command detects this automatically. When you agree to remove the binary, it runs brew uninstall handshake instead of deleting the file directly: 
Detected Homebrew install — running brew uninstall handshake...
✓ Binary removed via Homebrew
You do not need to run brew uninstall yourself — handshake uninstall handles it.

​
Manual Removal

If something goes wrong with the uninstall command, you can remove Handshake by hand:
1

Stop the daemon

pkill -f 'handshake serve'
2

Remove the login service

macOS:
launchctl unload ~/Library/LaunchAgents/com.handshake.daemon.plist
rm ~/Library/LaunchAgents/com.handshake.daemon.plist
Linux:
systemctl --user stop handshake
systemctl --user disable handshake
rm ~/.config/systemd/user/handshake.service
3

Remove the binary

rm $(which handshake)
4

Delete session data

rm -rf ~/.handshake
5

Remove agent config entries

Open each agent’s config file and remove the Handshake MCP server entry. The entry looks like:
{
  "handshake": {
    "type": "http",
    "url": "http://localhost:8765/mcp"
  }
}
Config file locations vary by agent. Check each agent’s documentation for the path.
If you just want to stop Handshake temporarily without uninstalling, use handshake uninstall-service to remove the login service. Your agent registrations stay in place and you can restart the daemon at any time with handshake serve or re-install the service with handshake install-service.