Codex

Message Codex from your phone. Codex keeps running on your computer. Relay carries the messages, the file-change approvals, and the final reply.

Pair this computer

npm install -g @relaymessenger/cli
relaymessenger pair

Approve the pairing in Relay, and the Agent Token is minted onto this computer. See the CLI for the full device flow and what pairing never sends.

Choose a path

Use the headless bridge for a standalone conversation. Use the project-scoped integration to get Relay tools inside the Codex runs you already do.

relaymessenger start --engine codex --dir ~/code/my-project

If an operation cannot be represented in full, Relay denies it rather than offering a blind Allow.

cd ~/code/my-project
relaymessenger install-codex

This merges into your existing configuration and preserves what is there:

File	What is added
`~/.codex/config.toml`	`[mcp_servers.relay]` and a completion `notify` command
`~/.codex/hooks.json`	A `PermissionRequest` hook
`~/.relaymessenger/codex-notify.json`	A local opt-in for this project root

How it behaves

Area	Behavior
Adapter pinning	The exact bundled `@agentclientprotocol/codex-acp` adapter drives Codex’s app-server protocol, launched directly with Node. There is no shell and no mutable `npx latest` lookup.
Streaming and sessions	The bridge preserves streamed ACP text, per-conversation session bindings, cancellation, and permission options, then posts the finished reply to Relay as one message.
File-change approvals carry the real diff	The bridge combines Codex’s earlier tool-call diff with the later permission request, so the phone sees the exact old and new text rather than a summary.
Idempotent MCP sends	MCP sends require a caller-stable `send_id`, so a retry with an unknown outcome reuses the same `message_id` and cannot post twice.
Per-project opt-in	`install-codex` records the project root you ran it from in `~/.relaymessenger/codex-notify.json`. Every other repository on the machine stays quiet until you opt it in separately.

relaymessenger doctor

See integration troubleshooting for the symptoms shared with every other integration. These are specific to this one.

Symptom	Cause and fix
Codex asks you to trust a hook handler	Expected right after `install-codex`. Codex prompts before running a newly installed `PermissionRequest` hook. Accept it once at the keyboard.
Nothing arrives for a project	That project root is not opted in. Run `relaymessenger install-codex` from the project you want.