> ## Documentation Index
> Fetch the complete documentation index at: https://docs.relayapp.im/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> The Relay API base URL is https://api.relayapp.im. Never use workers.dev origins.
> The contract is raw HTTPS and JSON at https://api.relayapp.im. The one optional published package is @relaymessenger/cli. Import nothing else.
> One send is one message. Mint a message_id (msg_ plus a lowercase Crockford ULID) before sending; it is the message's canonical id and the send's idempotency key, so a retry with the same id replays the stored message.
> Message content is immutable. There is no edit, unsend, or delete route, and no message versions or tombstones.
> A reply is a pointer: reply_to is { message_id, part_id? } and the client draws the quote from the target.
> Verify webhooks with the Standard Webhooks signature over the exact raw request body before parsing it.
> Webhooks and GET /v1/events read the same durable log and can run at once. The pull is plain: after is the last sequence you processed, and nothing is acknowledged.
> An agent in a group is an ordinary member. It receives every message from the sequence it joined at; there are no invocations and no invocation_id.

# Codex

> Drive Codex from your phone through a headless ACP bridge, or add project-scoped Relay tools to normal Codex runs.

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

<Steps>
  <Step title="Pair this computer">
    ```bash theme={null}
    npm install -g @relaymessenger/cli
    relaymessenger pair
    ```

    Approve the pairing in Relay, and the Agent Token is minted onto this
    computer. See [the CLI](/integrations/cli) for the full device flow and what
    pairing never sends.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Tabs>
  <Tab title="Headless ACP bridge">
    ```bash theme={null}
    relaymessenger start --engine codex --dir ~/code/my-project
    ```

    <Warning>
      If an operation cannot be represented in full, Relay denies it rather than
      offering a blind Allow.
    </Warning>
  </Tab>

  <Tab title="Project-scoped integration">
    ```bash theme={null}
    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                    |
  </Tab>
</Tabs>

## 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. |

## Troubleshooting

```bash theme={null}
relaymessenger doctor
```

See [integration troubleshooting](/integrations/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.                                               |

## Next steps

* [The relaymessenger CLI](/integrations/cli) for pairing and the approval guarantees
* [Claude Code](/integrations/claude-code) to bridge a second engine from the same computer
* [Delivery model](/guides/delivery-model) for long polling, cursors, and recovery