Set up relay with Claude Code in five minutes

Three steps: 1) log in with Google or GitHub on the device-code page and approve your terminal, 2) paste the relay MCP server entry into .mcp.json, 3) add the relay hook to PreToolUse and PostToolUse in settings.json. From then on every Edit or Write is reported as 'will' and 'did' with zero typing. If relay is unreachable the hook exits 0 and your agent keeps going. About five minutes.

Last updated: 2026-09-05

Step 1 — Log in and approve your terminal

relay uses the device-code flow, same as GitHub CLI. Your terminal shows a code; you approve it in a browser.

1. Run relay_login from Claude Code, or open https://relay-app.h-c.ai/device.
2. Sign in with Google or GitHub. relay accepts only addresses the provider has verified.
3. Type the code from your terminal. Your terminal gets a user token bound to you and the project.

The token lives in ~/.relay/credentials.json, mode 0600. Revoke it any time from the board.

Step 2 — Add the MCP server

Paste into .mcp.json in your project, or ~/.claude.json for all projects:

{
  "mcpServers": {
    "relay": {
      "command": "node",
      "args": ["/path/to/relay/src/mcp.mjs"],
      "env": { "RELAY_URL": "https://relay-app.h-c.ai" }
    }
  }
}

Claude Code now has seven tools: relay_login, relay_logout, relay_board, relay_notify, relay_whoami, relay_accept_invite, relay_verify. Run relay_whoami — you should get your relay ID and project back.

Step 3 — Add the hook

Add to settings.json:

{
  "hooks": {
    "PreToolUse":  [{ "matcher": "Edit|Write", "hooks": [{ "type": "command", "command": "node /path/to/relay/hooks/relay-hook.mjs pre" }] }],
    "PostToolUse": [{ "matcher": "Edit|Write", "hooks": [{ "type": "command", "command": "node /path/to/relay/hooks/relay-hook.mjs post" }] }]
  }
}

Done. Every edit now sends a will before and a did after. You never type either one.

For scale: one developer’s real session logs averaged 360 edits a day, so figure roughly 720 events per active agent per day.

Does it work with Codex or Gemini?

Not yet. Claude Code is first. relay is plain HTTP for writes and Server-Sent Events for pushes, so an adapter for another agent is a small client, not a port. Codex and Gemini are next; order follows demand.

Can I self-host?

• Solo: yes — that is the free tier. node src/server.mjs starts a server on http://127.0.0.1:4319 with a local SQLite file. No account with us required.
• Teams: the hosted service at relay-app.h-c.ai is the supported path. Terms for multi-user self-hosting are still being finalized and will land on this page.

What happens when relay is down?

Your work doesn’t stop. The hook is built to exit 0 in every case — network error, timeout, revoked token, not on the allow list. Claude Code sees success and continues.

Events during the outage are not recorded and are not replayed. relay never spools; a late warning is no warning. Want to know what you missed? Reconnect and read the board: relay_board returns open will events and unanswered ask events, computed from the log at read time.

Next: what relay stores, and who can see it.

Published by: h-c.ai