Setup Guide — Relay

Create your Relay account

Head to tryrelayapp.com/get-started and sign up with your email address. Takes about 30 seconds.

🌐

Screenshot: get-started page / sign-up form

Copy your Relay Token

After signing up, your Relay Token is displayed on the dashboard. It looks like rt_xxxxxxxxxxxx. Copy it — you'll paste it into the Mac app in the next steps.

🔑

Screenshot: dashboard showing Relay Token

Get TestFlight on your Mac

Relay is distributed through TestFlight during beta. Open the Mac App Store and search for TestFlight, then install it. Requires macOS 12 or later.

🛍

Screenshot: TestFlight in the Mac App Store

Install Relay via TestFlight

Open TestFlight and accept the invite link from the Relay beta. Click Install. The app will appear in your Applications folder.

💡 Don't have an invite link yet? Sign up and one will be included in your welcome email.

📲

Screenshot: Relay in TestFlight — Install button

Launch Relay from your menu bar

Open Relay from Applications. A small antenna icon will appear in your Mac menu bar. Click it to open the task flyout.

📡

Screenshot: Relay antenna icon in macOS menu bar

Connect your account

Click the gear icon in the top-right of the flyout to open Settings. Paste your Relay Token into the field and click Connect.

⚙️

Screenshot: Relay Settings — token field + Connect button

✓

Your task board is live

Relay will load your task board. It's empty for now — that changes once you connect your agents.

📋

Screenshot: Relay flyout showing connected, empty task board

Prerequisites

You'll need your Relay Token from the Mac App setup (the rt_xxxx string), Node.js 18+, and Claude Code installed. If you haven't completed the Mac App setup yet,

Add Relay to Claude Code

Run this command in your terminal, replacing rt_xxxx with your actual token. This registers the Relay MCP server with Claude Code globally.

Terminal

claude mcp add relay \
  -e RELAY_TOKEN=rt_xxxx \
  -- npx -y @relayctl/mcp

💡 Prefer the JSON config? Add this to ~/.claude/claude_code_config.json under "mcpServers":

"relay": { "command": "npx", "args": ["-y", "@relayctl/mcp"], "env": { "RELAY_TOKEN": "rt_xxxx" } }

💻

Screenshot: terminal running the claude mcp add command

Open a new Claude Code session

Start or restart Claude Code. MCP servers are loaded at session start. At the beginning of any session, run relay_summary to orient your agent against the current task state.

Claude Code prompt

relay_summary

🤖

Screenshot: Claude Code session with relay_summary output

Agents post tasks automatically

Claude Code agents now have access to five tools. They'll use them as they work — no extra prompting required once the MCP is wired up.

Available tools

relay_summary   → orient at session start (counts + blocked)
relay_create    → register a new task
relay_update    → post progress or change status
relay_done      → mark complete
relay_block     → flag as blocked — surfaces to you immediately

🔧

Screenshot: Claude Code using relay_create mid-task

Watch tasks appear in your menu bar

Every task your agent creates or updates shows up in the Relay flyout in real time. Swipe right on a task to update its status. Swipe left to block it. The menu bar icon turns pink the moment anything needs your attention.

📡

Screenshot: Relay flyout showing live agent tasks

✓

You're fully set up

Prerequisites

You'll need your Relay Token (rt_xxxx), Node.js 18+, and the OpenAI Codex CLI installed. If you haven't set up the Mac app yet,

Install Codex CLI

npm install -g @openai/codex

Add Relay to your Codex config

Open (or create) ~/.codex/config.yaml and add the Relay MCP server block below. Replace rt_xxxx with your actual token.

~/.codex/config.yaml

mcp_servers:
  - name: relay
    type: stdio
    command: npx
    args:
      - -y
      - "@relayctl/mcp"
    env:
      RELAY_TOKEN: rt_xxxx

💡 If ~/.codex/ doesn't exist yet, run codex once to initialize it, then edit the config.

Start a Codex session and verify

Launch Codex in your project directory. At the start of any session, ask it to run relay_summary to confirm the MCP connection and see current task state.

Terminal

codex

In the Codex session

Run relay_summary to show current task state.

⚡

Screenshot: Codex session showing relay_summary output

Available Relay tools

Codex will discover and use these tools automatically as it works through tasks.

Available tools

relay_summary   → orient at session start (counts + blocked)
relay_create    → register a new task
relay_update    → post progress or change status
relay_done      → mark complete
relay_block     → flag as blocked — surfaces to you immediately

✓

Codex is connected

Prerequisites

You'll need your Relay Token (rt_xxxx), Node.js 18+, and the Gemini CLI installed. If you haven't set up the Mac app yet,

Install Gemini CLI

npm install -g @google/gemini-cli

Add Relay to your Gemini settings

Open (or create) ~/.gemini/settings.json and add the mcpServers block. Replace rt_xxxx with your actual Relay Token.

~/.gemini/settings.json

{
  "mcpServers": {
    "relay": {
      "command": "npx",
      "args": ["-y", "@relayctl/mcp"],
      "env": {
        "RELAY_TOKEN": "rt_xxxx"
      }
    }
  }
}

💡 If you already have other MCP servers in settings.json, just add the "relay" key inside your existing mcpServers object.

Start a Gemini session and verify

Launch Gemini CLI in your project directory. MCP servers load at session start. Ask it to run relay_summary to confirm the connection.

Terminal

gemini

In the Gemini session

Run relay_summary to show current task state.

🔷

Screenshot: Gemini CLI session showing relay_summary output

Available Relay tools

Gemini will discover and call these tools automatically throughout its work loop.

Available tools

relay_summary   → orient at session start (counts + blocked)
relay_create    → register a new task
relay_update    → post progress or change status
relay_done      → mark complete
relay_block     → flag as blocked — surfaces to you immediately

✓

Gemini is connected

Get up and runningin under 5 minutes

Get up and running
in under 5 minutes