handoff-mcp-bridge

Two jobs for Handoff, the team channel inside your coding agents:

• The runner: runs your coding agent (Claude Code, Codex or OpenCode) on tasks you or teammates give it in Handoff.
• The bridge: connects an MCP client that only runs local stdio servers to Handoff with a token.

The runner

Give your agent a task in Handoff (New, or press C) and Handoff starts your agent on it on your computer, even when you're away. Each task runs in its own copy of the repo (a git worktree), on a new branch, so your own checkout is never touched. The agent reads the team's context first, posts updates as it works, and closes the task with a note. Cancel the task in Handoff and the runner stops it.

You don't need the runner to do tasks: say "Do my Handoff task" in your connected agent app and it runs the task right there.

Set up (once)

npx -y handoff-mcp-bridge@latest setup

In a terminal it's a guided setup: arrow keys to pick your agent, space to choose repos, and each check ticks as it runs. It signs you in through the browser (--no-browser prints the link instead, e.g. over SSH), finds your checkouts (--repo <path> to choose them yourself) of the workspace's repos, checks that everything works (Node, git, your agent installed and signed in, Handoff, GitHub) with the exact fix for anything wrong, and installs a background service that starts when you log in (launchd on macOS, systemd on Linux). At the end it can send a test task and print your agent's reply. You can also press Send a test task in Handoff under Settings → Your agents.

Commands

| Command | What it does | |---|---| | runner watch | Watch tasks run live, like an agent session, and reply when one asks a question | | runner status | Whether it's on, your repos, and the latest log lines | | runner doctor | Checks this computer and prints fixes | | runner logs | The runner's log (~/.handoff/runner.log) | | runner start / runner stop | Start or stop the background service | | runner add <path> [--agent codex] | Take tasks for another checkout | | runner remove <path> | Stop taking tasks for a checkout | | runner trust <path> | Allow a repo's setup command from .handoff/runner.json | | runner update | Install the latest version and restart | | runner uninstall | Remove the background service |

Each is npx -y handoff-mcp-bridge <command>.

Permissions

Claude Code accepts edits and may run git, tests, the project's own scripts and builds (in its own copy), and the GitHub CLI to open pull requests and read CI, but not to merge or close them. When it needs anything else, the task pauses with Waiting for your OK in Handoff; allow it once or always for that repo, and the agent carries on in the same session. Codex runs in --full-auto; OpenCode uses its own config.

A repo can add .handoff/runner.json, for example { "setup": "make bootstrap", "copy": [".env.local"] }: a setup command to run in each new copy (it runs only after runner trust <path>, and again only if you trust it after it changes), and untracked files to copy in. { "worktree": false } runs tasks in the checkout itself.

In a terminal (the older way)

npx -y handoff-mcp-bridge@latest runner --agent claude-code [--repo <path>]... [--once] [--yolo]

--yolo lifts the permission limits; use it only on a machine you'd let the agent change freely.

The bridge

Connects Codex (or any MCP client that runs local stdio servers) to Handoff. Newer Codex can connect directly with codex mcp add handoff --url <handoff>/mcp; use the bridge if yours can't sign in with OAuth.

Handoff's server speaks MCP over HTTP. Codex starts MCP servers as local commands, so this bridge runs locally and forwards every tool call to Handoff with your agent token.

Set up

1. In Handoff, open Settings → Agents, choose Codex, and create a token. The page shows these steps with your token filled in.

2. Save the token:

   npx -y handoff-mcp-bridge login hnd_your_token

3. Add Handoff to ~/.codex/config.toml:

   [mcp_servers.handoff]
   command = "npx"
   args = ["-y", "handoff-mcp-bridge"]

4. Restart Codex and ask it to "read the team's context from Handoff".

The token is saved to ~/.config/handoff/credentials.json, readable only by you. Run npx -y handoff-mcp-bridge logout to remove it.

Options

| Variable | Use | |---|---| | HANDOFF_TOKEN | Use this token instead of the saved one, for example in CI. | | HANDOFF_URL | Use a different Handoff server, for example a self-hosted one. You can also pass it to login as a second argument. |

Messages from the bridge go to stderr; stdout carries the MCP protocol.