Skip to main content

​
Before you start

  • Codex, installed and signed in.
  • Node.js 22.22.3 or newer.

​
Connect

Run this in the folder where you work to connect codex to Relay.
In an unlinked folder, this creates a new agent by default. If the folder is already linked, it uses that agent. Use --handle or --name to customize the new agent. then scan the QR with Relay on your phone to add the agent, and send it a message. Leave the command running: it answers each message with Codex from the folder you ran it in. Control-C stops it.

​
Do it by hand

​
Send it a message

Open Relay on your phone and message the handle. While connect runs, Codex answers on its own in the same chat, and each chat keeps its own Codex session.

​
What it can do

These come from the connection code for codex and the Relay MCP tool list.

​
When it fails

  • No reply yet. Run: relay watch @<handle> Connect is not running, or Codex is still working; run connect again and it answers from there.
Use the CLI guide for prompt, token, and restart errors. Selection. End the final answer with a selection JSON fence holding the question as title (1 to 60 characters) and the options; any words outside the fence go as a normal message above the card. The app-server prompt preserves selected_values, reply_to, and ordered rich parts as data alongside the readable bullet text. Payments. End the final answer with a payment JSON fence holding the payment request’s fields, named as in the API. Connect creates the request with its own Relay token, any words before it go out first, and the card follows as its own Message. If Relay refuses the request, the terminal says why and sends no card.

​
Next steps