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

# Claude Code

> Drive Claude Code from your phone through a headless ACP bridge or a native Claude channel plugin.

Text Claude Code from your phone. Claude keeps running on your computer with its
own credentials, tools, and files. Relay carries the messages, the permission
cards, and the final reply.

Authenticate Claude on the computer first. Interactive terminal authentication
and form elicitation are not proxied through Relay.

## Requirements

| Requirement | Detail                                                                                                               |
| ----------- | -------------------------------------------------------------------------------------------------------------------- |
| Node.js     | 22.18 or newer for the `relaymessenger` CLI. The channel plugin runtime itself needs 20.11 or newer                  |
| Claude Code | A build with channel support. Channels are a research preview, and Team or Enterprise organizations must enable them |
| Relay agent | An agent and its Agent Token. See [Create and connect an agent](/guides/your-agent)                                  |

<Tip>
  Give the bridge its own Relay agent when a webhook backend already serves one,
  so each turn is answered once and by one runtime.
</Tip>

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

    Scan the terminal QR code or enter its short code in Relay, and approve the
    pairing there. The Agent Token is minted onto this computer and never
    travels to the phone. 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 conversation that runs without a terminal
    open. Use the channel plugin to push messages into a Claude session you are
    already sitting in.
  </Step>

  <Step title="Message the agent">
    A message, or a quick burst of messages, becomes one turn. Relay shows the
    agent typing while it works, then posts one final reply. Supported tool
    permission requests arrive as owner-only messages carrying an id. Answer
    either path by replying `yes <id>` or `no <id>`.
  </Step>
</Steps>

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

  <Tab title="Native channel plugin">
    ```bash theme={null}
    relaymessenger install-claude
    claude --dangerously-load-development-channels plugin:relay@relaymessenger-bundled
    ```

    <Warning>
      Claude Code channels are a research preview.
    </Warning>
  </Tab>
</Tabs>

## What the channel plugin is

The channel plugin is an open-source MCP stdio server for Claude Code's channel
contract. It publishes to npm as `relay-claude-channel` and is built from
`integrations/claude-code` in the
[Relay-SDK repository](https://github.com/relaymessenger/Relay-SDK).

`relaymessenger install-claude` installs the copy bundled inside the CLI, so
the three commands above are the whole install. Reach for the package name when
you are reading its source, filing an issue, or auditing what runs on your
machine.

## Install from GitHub instead

Claude Code can add the same plugin without the CLI:

```
/plugin marketplace add relaymessenger/Relay-SDK
/plugin install relay@relaymessenger
```

You still need `relaymessenger pair`, or a hand-written
`~/.claude/channels/relay/.env`, to supply the Agent Token.

## Verify without printing the token

```bash theme={null}
node <installed-plugin-directory>/runtime/server.mjs --check
```

The check validates the channel configuration, the API origin, and the owner
pin. It never prints the Agent Token. Run `/relay:configure` inside Claude for
the same verification from the session.

## How it behaves

| Area                  | Behavior                                                                                                                                                                                                                                                                  |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Adapter pinning       | `relaymessenger` launches its exact bundled `@agentclientprotocol/claude-agent-acp` entrypoint directly with Node, with no shell and no mutable `npx latest` lookup. The adapter version cannot change under you between runs.                                            |
| Session persistence   | Conversation-to-session bindings survive bridge restarts when the adapter supports session loading. Where it does not, a restart begins a new session.                                                                                                                    |
| Permission previews   | Claude supplies a bounded permission input preview. Relay offers remote Allow only when that preview is complete JSON that Claude did not truncate. Otherwise the phone can deny, and you approve at the keyboard.                                                        |
| Channel plugin tools  | The plugin follows Claude's MCP channel contract: it emits `notifications/claude/channel`, exposes retry-safe `reply` and `acknowledge` tools, and relays permission notifications.                                                                                       |
| One session per agent | A second Claude session on the same agent fails closed instead of answering the same messages twice. Point the second session at a different Relay agent.                                                                                                                 |
| Redelivery            | Channel notifications are unacknowledged at Claude's transport layer, so the plugin re-notifies every 30 seconds until Claude calls `acknowledge`, and replays after a restart. Delivery is at least once. Reconcile before repeating a deploy, a deletion, or a payment. |
| Identity protection   | `relaymessenger install-claude` validates the bundled marketplace, copies it into the paired account's private runtime directory, and writes the token, API origin, and owner pin to an owner-only channel `.env`. It refuses to replace a different configured identity. |

## 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                                                                                                                                                                |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Channel events stop arriving | The Claude session closed. Channel events flow only while that session stays open. Use the headless ACP bridge for a conversation that does not need a terminal.             |
| The plugin will not load     | Custom channels require the development-channel flag unless your organization explicitly allowlists the plugin. Team and Enterprise organizations must also enable channels. |

## Next steps

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