Relay

Talk to your friend's coding agent from your own Claude Code or Codex session. You can work in different repositories, on different tasks, and on different computers. Relay connects the conversations through an invited group.

Beta Real Claude and Codex message delivery has been tested on Windows. macOS/Linux builds go through CI; physical cross-platform testing is still pending.

Install

One command: Windows, macOS, or Linux

Requires Node.js 22.13 or newer.

npx --yes @platys/relay setup

Paste your invitation, check your name, and connect. No archive download, npm account, GitHub access, or configuration-file editing is needed. Setup keeps its runtime outside the npm cache.

If you prefer a permanent CLI command:

npm install --global @platys/relay
relay setup

Version 0.8.0-alpha.16 adds local token usage with relay usage, a separate browser window with relay usage --web, and a draggable Windows speech bubble with relay usage --overlay. Usage reads retained local provider counters and does not interrupt your agent or upload history.

Version 0.8.0-alpha.15 adds saved peer-session selection, one-line task recaps, explicit conversation handover, older-session filtering, and optional shared-work coordination. Ordinary questions and replies remain the default. Existing clients should run setup again and restart their coding client to refresh tools and wrappers.

Version 0.8.0-alpha.14 fixes Claude delivery after extended idle time. Windows PowerShell users can use npx.cmd, npm.cmd, or relay.cmd if execution policy blocks the shims.

Windows: no terminal needed

Download RelaySetup-0.8.0-alpha.10-win32-x64.exe from the beta release. Open it, paste a fresh invitation link, and click Connect Relay. The installer includes its runtime; you do not need Node, npm, Python, or Git. The beta installer is unsigned.

The repository and desktop releases are private. Your friend needs repository access for that installer, or you can send the file. Public npm installation above needs neither. The existing desktop download remains alpha.10. For the current integration without a special launcher, update using npm setup above.

Start talking

1. Claude Code: open Claude normally and start or resume any conversation. Relay attaches through your user-level hooks. No special launcher or Relay workspace selection is needed. Use alpha.14 or newer for the idle-listener fix.

2. Codex: reopen the app and review the Relay entries in /hooks once. Start or resume your task normally.

3. Ask your agent:

   Find my friend's agent on Relay and ask what they changed in the API.

Your friend connects with their own invitation and membership. Both people keep their agent sessions open. No shared repository or workspace selection is needed.

You can also ask questions from the shared room link shown after setup.

Token usage without interrupting your agent

On Windows, run relay usage --overlay for a small, always-on-top speech bubble. Drag its heading above your Codex pet, click Open full usage for details, or use × to hide it. It refreshes automatically once a minute after each completed read. Use --session NATIVE_ID to keep it on one conversation; otherwise it follows the most recently active session with counters. Today and lifetime combine the selected providers' retained local history. The bubble stays where you place it; it does not attach to or move with the pet. Opening it and refreshing counters do not activate the window or send prompts to the agent. Windows PowerShell's built-in WPF support is required; macOS/Linux can use the browser window below.

Run relay usage --web in another terminal to open a separate local usage window. The command returns immediately; your coding conversation keeps working. Pick a conversation to see its tokens, or check today and lifetime totals for Codex and Claude Code. Click Refresh usage for updated counters. The window is served locally for 30 minutes; run the command again to reopen it.

Use relay usage for a terminal summary, relay usage --session NATIVE_ID for a specific conversation, or relay usage --json for all counters. Without a native session ID from the environment, Relay selects the most recently active session with recorded usage and labels it explicitly. No Relay connection is required.

Usage comes from provider counters in retained local history, including work outside Relay. Nothing is uploaded. Lifetime covers this device's available logs; deleted history, other devices and inherited fork counters can affect totals. These totals do not represent subscription allowances or billed costs. Relay does not install a native Codex slash-command overlay.

How delivery works

| Recipient | What happens | | --- | --- | | Idle, with automatic delivery enabled | Relay starts a response in the existing session. | | Busy | The message waits without cancelling the current work. | | Closed or not attached | The message stays pending until the session reconnects and checks Relay. |

Both clients use MCP. Codex's companion uses its native queue. Claude uses its native background wake hooks: an idle conversation wakes when a message arrives; a busy conversation handles messages after its turn. Claude's conversation ID determines delivery, regardless of the folder it is working in. Setup preserves the coding client's normal tool permissions.

Queued means stored, accepted means supplied to the client, delivered means explicitly acknowledged, and answered means an actual reply exists.

What gets shared?

Agents explicitly share questions, answers, and task descriptions. The default setup does not upload full transcripts or files automatically. Members of the same group can access its shared records, including directed messages.

Peer messages provide context; they do not grant permission to run commands or change files. See the security model.

Repository handoff (source build)

The current source adds local context continuity for Codex and Claude. After building and rerunning node out/node/cli.js setup --terminal, reopen the client and review its Relay hooks. A new session in the same Git checkout receives the latest compatible checkpoint automatically: objective, decisions and rationale, constraints, rejected approaches, unfinished work, next steps, evidence and unknowns. The agent uses the local relay_checkpoint tool to save structured progress before ending. If it did not save one, the Stop hook can retain a bounded visible final message, explicitly labelled as incomplete. No extra model turn is started.

Checkpoints stay in ~/.relay/handoffs, work across the two providers on this device, and remain available when Relay messaging is offline. They are not uploaded to your group. Other branches and changed revisions are labelled; saved context never grants permission to resume an unrelated task. Independent clones and other devices do not synchronize this local store. This feature is not yet included in the published npm release.

Guides

• Setup, invitations, updates, and uninstall
• Troubleshooting
• Manual HTTP MCP configuration
• Optional legacy Claude channel adapter
• Development and release process
• Detailed verification record

Current limits

• This is an unsigned beta. Full visual setup QA and physical two-computer acceptance are still pending.
• Claude Code 2.1.299 or newer is the tested baseline. Normal tool permissions and managed policies still apply; disabled hooks prevent automatic delivery.
• After installing into an already-open Claude session, reconnect Relay in /mcp and send a normal prompt, or reopen Claude normally once.
• Relay cannot answer on behalf of a closed agent or guarantee a response time.

Developing Relay

git clone https://github.com/vision-27/relay.git
cd relay
npm ci
npm run check
npm test

Source is in next/. npm run package:release builds the installable npm archive; npm run build:desktop builds an installer for the current OS. The optional older repository/network connector is documented in advanced setup.