handoff-relay

Human-approved context handoffs between coding agents.

Handoff lets Codex, Claude Code, Cursor, and other MCP-capable agents send bounded Relay Packets between teammates. An agent drafts the packet, a human reviews what leaves, the recipient reviews what arrives, and only then does their agent hydrate the selected context.

Team Setup

On the host/admin machine, create a LAN-reachable workspace and first invite:

npx -y handoff-relay start --lan --install-mcp codex --invite alice

Add more teammates later with invite:

npx -y handoff-relay invite bob

Rerunning start --invite <handle> or invite <handle> before that teammate joins reprints the same active invite.

Each teammate runs their own join command:

npx -y handoff-relay join http://<handoff-host>:3737/invite/<invite-token> --install-mcp codex

Use --install-mcp claude for Claude Code or --install-mcp cursor for Cursor.

start creates the shared workspace, host profile, SQLite coordination database, reachable server URL, MCP config when requested, and a background notification watcher. join stores the teammate's local profile and member credentials, then starts that teammate's local notification watcher. To opt out later, run npx -y handoff-relay watch --stop.

For dedicated self-hosted servers started with server start on a non-loopback host, first-workspace creation requires HANDOFF_WORKSPACE_BOOTSTRAP_TOKEN or a temporary HANDOFF_ALLOW_PUBLIC_WORKSPACE_BOOTSTRAP=1 bootstrap window. See docs/local-self-hosting.md and docs/advanced-manual-setup.md for the manual setup flow.

Use With Agents

Handoff is meant to run behind your coding agent as a stdio MCP server. The normal workflow happens inside the agent, not by manually copying CLI output around.

Default profile-backed MCP command:

npx -y handoff-relay server mcp --profile default --agent-approvals

MCP JSON:

{
  "mcpServers": {
    "handoff": {
      "command": "npx",
      "args": ["-y", "handoff-relay", "server", "mcp", "--profile", "default", "--agent-approvals"]
    }
  }
}

Ask the sending agent:

Use Handoff to create a Relay Packet for @alice from this session.
Include files touched, commands run, known failures, current hypothesis, evidence excerpts, and suggested next steps.
Draft with relay_share or relay_ask. Show me the packet summary, claims, evidence, expiry, and redaction report before sending.
If I approve, call relay_send_approved.

Ask the receiving agent:

Check my Handoff inbox.
Call relay_review_next and show me the Relay Packet before hydration.
If I approve, call relay_hydrate_approved.

Client Setup

Codex can be wired automatically while hosting or joining:

npx -y handoff-relay start --lan --install-mcp codex --invite alice
npx -y handoff-relay join <invite-link> --install-mcp codex

Codex TOML:

[mcp_servers.handoff]
command = "npx"
args = ["-y", "handoff-relay", "server", "mcp", "--profile", "default", "--agent-approvals"]
startup_timeout_sec = 10
tool_timeout_sec = 60
enabled = true

Claude Code can be wired automatically while hosting or joining:

npx -y handoff-relay start --lan --install-mcp claude --invite alice
npx -y handoff-relay join <invite-link> --install-mcp claude

Cursor can be wired automatically while hosting or joining:

npx -y handoff-relay start --lan --install-mcp cursor --invite alice
npx -y handoff-relay join <invite-link> --install-mcp cursor

Claude Desktop, Claude Code project config, Cursor, and other mcpServers clients can use the JSON config above.

Human Approval

Profile setup uses agent-confirmed approvals by default. After the agent shows you the packet and you explicitly tell it to send, approve, or hydrate, the MCP process requests the same short-lived approval token through the configured Handoff backend. Approval secrets stay out of MCP schemas and config.

Strict mode is still available by omitting --agent-approvals. Agents can draft, list, and read packets, but they need a pasted human approval token before sending, hydrating, or approving a reply:

npx -y handoff-relay approval-token <packet-id> --action send
npx -y handoff-relay approval-token <packet-id> --action hydrate
npx -y handoff-relay approval-token <reply-packet-id> --action reply

Strict profile-backed MCP command:

npx -y handoff-relay server mcp --profile default

Optional CLI Install

You do not need a global install for MCP configs. npx -y handoff-relay ... is usually better because the MCP client can launch Handoff directly.

Install globally only if you want shorter local commands:

npm install -g handoff-relay
handoff doctor

handoff-relay is the npm package name. handoff is the installed CLI command.

Requires Node.js 20+.

CLI Commands

handoff start [--lan] [--install-mcp codex|claude|cursor]
handoff stop
handoff restart
handoff invite <handle>
handoff join <invite-link> [--install-mcp codex|claude|cursor]
handoff leave
handoff delete-profile [--delete-data]
handoff uninstall-mcp [--client codex|claude|cursor|all]
handoff remove-member <handle-or-id>
handoff doctor
handoff server mcp --profile default --agent-approvals
handoff approval-token <packet-id> --action send|hydrate|reply
handoff inbox
handoff status <packet-id>
handoff history
handoff audit
handoff watch --status
handoff watch --stop
handoff watch --background
handoff demo two-user

MCP Tools

| Tool | Purpose | | ------------------------ | -------------------------------------------------------- | | relay_ask | Draft an ask packet for another teammate. | | relay_share | Draft a share packet from current context. | | relay_update_draft | Edit a draft before approval. | | relay_send_approved | Approve and send an ask, share, or reply packet. | | relay_review_next | Open the next actionable inbox packet for review. | | relay_inbox | List packets addressed to the current member. | | relay_review | Mark a chosen packet reviewed and return next actions. | | relay_hydrate_approved | Hydrate a reviewed packet after human approval. | | relay_approve | Compatibility approval tool. | | relay_reply | Draft a reply packet. | | relay_clarify | Request more information or evidence. | | relay_decline | Decline an addressed packet. | | relay_archive | Archive a readable packet. | | relay_search | Search permitted packet history without hydration. | | relay_history | List drafts, sent packets, open work, or closed packets. | | relay_audit | List packet audit receipts. |

Links

• GitHub: https://github.com/0dust/handoff
• Codex setup: https://github.com/0dust/handoff/blob/main/docs/codex-setup.md
• Claude Code setup: https://github.com/0dust/handoff/blob/main/docs/claude-code-setup.md
• Generic MCP setup: https://github.com/0dust/handoff/blob/main/docs/generic-mcp-setup.md
• Troubleshooting: https://github.com/0dust/handoff/blob/main/docs/troubleshooting.md
• License: MIT