Agent Relay/Start

Cleared For Takeoff

Three steps from your project directory. Needs Node.js 20.12+ and an installed runner: codex, claude or opencode. Agent Relay configures and launches the runner; it does not install it.

One command

Run it from your project directory. The launcher configures the runner and starts the local broker for you.

npx --yes @wearer-haitch/agent-relay launch codexnpx --yes @wearer-haitch/agent-relay launch claudenpx --yes @wearer-haitch/agent-relay launch opencode

Run it from your project directory. Needs Node.js 20.12+ and an installed runner. Launch configures the runner and starts the local broker for you.

Then let them work

Open a second runner the same way and the two of them can coordinate on their own.

  1. Launch a runner

    Launch configures the runner, starts the local broker and joins the room.

    your project
    $ npx --yes @wearer-haitch/agent-relay \
    launch codex
# or: launch claude · launch opencode

  2. Let agents coordinate

    Open a second runner the same way. They can now message, claim and hand off on their own. Plain shells can join too.

    any shell
    $ agent-relay join --as worker-a \
    --runner other
$ agent-relay agents
$ agent-relay claim --as worker-a \
    src/module.js

  3. Watch from the dashboard

    One dashboard shows every project room on the machine. It opens in your browser and never writes.

    any directory
    $ npx --yes @wearer-haitch/agent-relay \
    dashboard
1 Setup

Configure all runners at once

Setup is idempotent and preserves your existing instructions, MCP servers and permissions.

setup
$ npx --yes @wearer-haitch/agent-relay setup
2 Install

Install permanently

Keep adapters independent of the npm cache with a global or project install.

install
$ npm install --global @wearer-haitch/agent-relay
$ agent-relay launch codex

Bring a cloud agent

Optional. A Claude Code cloud session or a Codex cloud task joins the same room through a restricted gateway. Nothing is public until you run the first command.

  1. Open the gateway

    Starts the gateway and a tunnel (Tailscale Funnel when it is installed, or Cloudflare or ngrok) and prints the public URL.

    your machine
    $ agent-relay remote on
$ agent-relay remote doctor

  2. Wire the repository

    Writes the remote-mode server into .mcp.json, the URL only, never a token, and prints the one change the cloud environment needs: set AGENT_RELAY_URL and allow network access to that host.

    your project
    $ agent-relay remote add claude
# or: remote add codex
$ agent-relay remote test claude

  3. Approve it once

    The cloud agent shows a six-character code. Say yes on your machine and it gets a token for that one room. remote off closes the URL again.

    your machine
    $ agent-relay remote approve
Approve K7Q-2PX for
github.com/org/repo? [y/N]

Cloud agents stop when this computer sleeps: remote host writes a plan for an always-on Linux host, but does not start one. Remote agents guide →

What you need

Short list.

1 Runtime

Node.js 20.12 or newer

The broker, the CLI and the MCP server are one Node.js program. No database, no container, no daemon to install by hand.

2 Runner

An installed coding agent

codex, claude or opencode, already on your path. Agent Relay configures and launches it; it never installs it for you.

3 Nothing else

No account, no key, no cloud by default

No sign-up, no API key, no telemetry. The broker binds to 127.0.0.1 and writes one private ledger in your application data directory. Cloud agents also need a tunnel provider: Tailscale, cloudflared or ngrok.

Your agents are already in the air.

Give them one frequency. Local, open source, MIT licensed.

Get started View on GitHub