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

# Text your coding agent

> Connect Claude Code, Codex, Hermes Agent, or OpenClaw to Relay and drive it from your phone.

`relayapp` connects an agent running on your computer to a Relay conversation.
Relay carries messages, approval cards, and final replies; Claude Code, Codex,
Hermes Agent, or OpenClaw keeps running locally with its own credentials, tools,
files, and session state.

## The 60-second path

<Steps>
  <Step title="Install and pair">
    ```bash theme={null}
    npm install -g relayapp@0.2.0
    relayapp pair
    ```

    Scan the terminal QR code or enter its short code in Relay. Pairing creates
    a normal Relay agent, returns its Agent Token only to this computer, and
    pins your Relay user id as the only default sender allowed to drive it.
  </Step>

  <Step title="Start an engine bridge">
    ```bash theme={null}
    cd ~/code/my-project
    relayapp start --engine claude
    # or: --engine codex
    # or: --engine hermes
    ```

    Claude and Codex use adapters bundled at exact versions in `relayapp`.
    Hermes uses the `hermes acp` command already installed on your machine;
    check it first with `hermes acp --check`.
  </Step>

  <Step title="Text the new agent">
    A message, or a quick burst of messages, becomes one turn. Relay shows the
    agent typing while it works, posts one final reply, and presents supported
    tool permission requests as owner-only Allow/Deny cards.
  </Step>
</Steps>

## Four supported integrations

| Integration  | Relay path                                                                          | Best when                                                                                   |
| ------------ | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| Claude Code  | `relayapp start --engine claude` over ACP, or the native Claude channel plugin      | You want a headless bridge or messages pushed into an already-open Claude session           |
| Codex        | `relayapp start --engine codex` over ACP, plus optional notify/MCP/permission hooks | You want a headless conversation or project-scoped Relay tools in normal Codex runs         |
| Hermes Agent | `relayapp start --engine hermes` over `hermes acp`                                  | You already run Hermes locally and want its persisted sessions and permission flow in Relay |
| OpenClaw     | Native OpenClaw channel installed by `relayapp install-openclaw`                    | OpenClaw owns the agent runtime and Relay should be one of its messaging channels           |

OpenClaw is intentionally not an ACP engine preset. Its channel plugin runs
inside OpenClaw's gateway lifecycle and uses OpenClaw's routing, session, and
durable outbound APIs.

## Claude Code

### Headless ACP bridge

```bash theme={null}
relayapp start --engine claude --dir ~/code/my-project
```

`relayapp` launches its exact bundled `@agentclientprotocol/claude-agent-acp`
entrypoint directly with Node, without a shell or a mutable `npx latest`
lookup. Conversation-to-session bindings survive bridge restarts when the
adapter supports session loading. Claude must already be authenticated on the
computer. Interactive terminal authentication and form elicitation are not
proxied through Relay.

### Native channel plugin

```bash theme={null}
relayapp install-claude
claude --dangerously-load-development-channels plugin:relay@relayapp-bundled
```

The installer validates the bundled marketplace, copies it into the paired
account's private runtime directory, installs `relay@relayapp-bundled`, and
writes the token, API origin, and owner pin to an owner-only channel `.env`.
It refuses to replace a different configured identity.

<Warning>
  Claude Code channels are a research preview. Custom channels require the
  development-channel flag unless an organization explicitly allowlists the
  plugin; Team and Enterprise organizations must also enable channels. Channel
  events arrive only while that Claude session remains open.
</Warning>

The plugin follows Claude's MCP channel contract: it emits
`notifications/claude/channel`, exposes retry-safe `reply` and `acknowledge`
tools, and relays permission notifications. Claude currently supplies only a
bounded permission input preview. Relay offers remote Allow only when that
preview is complete JSON below Claude's truncation boundary; otherwise the
phone can deny and approval must happen locally.

## Codex

### Headless ACP bridge

```bash theme={null}
relayapp start --engine codex --dir ~/code/my-project
```

The exact bundled `@agentclientprotocol/codex-acp` adapter drives Codex's
app-server protocol. Relay preserves streamed text, per-conversation session
bindings, cancellation, and permission options. For file-change approvals,
the bridge combines Codex's earlier tool-call diff with the later permission
request so the phone sees the exact old and new text. If the operation cannot
be represented in full, Relay denies instead of offering a blind Allow.

### Project-scoped Codex integration

```bash theme={null}
cd ~/code/my-project
relayapp install-codex
```

This merges without clobbering user configuration:

* `[mcp_servers.relay]` and a completion `notify` command in
  `~/.codex/config.toml`;
* a `PermissionRequest` hook in `~/.codex/hooks.json`;
* a local opt-in for this project root in `~/.relayapp/codex-notify.json`.

Other projects remain suppressed until you opt them in separately. Codex may
ask you to trust a newly installed hook handler. MCP sends require a
caller-stable `send_id`, so an unknown-outcome retry can reuse the same Relay
idempotency key without posting twice.

## Hermes Agent

Install and authenticate Hermes using its official setup, then verify its ACP
surface before starting Relay:

```bash theme={null}
hermes acp --check
relayapp start --engine hermes --dir ~/code/my-project
```

Relay launches `hermes acp` shell-free and leaves Hermes configuration,
provider credentials, and `~/.hermes/state.db` under Hermes ownership.

The current Hermes ACP server supports persisted session load and resume,
streamed assistant and reasoning content, tool activity, diffs, cancellation,
plan updates, and permission choices.

<Note>
  Hermes waits 60 seconds for an ACP permission decision, so Relay uses a
  55-second phone window and denies on timeout or transport failure.
</Note>

The reference implementation audited for this release is Hermes Agent 0.18.2.
`relayapp doctor` reports the installed version and runs `hermes acp --check`;
the readiness check, rather than an unverified version-string cutoff, decides
whether the local installation can start. Installing and upgrading Hermes
stays entirely in your hands.

## OpenClaw

```bash theme={null}
npm install -g relayapp@0.2.0
relayapp pair
relayapp install-openclaw
```

The installer persists the bundled OpenClaw plugin archive, runs OpenClaw's
plugin installer, adds only the Relay plugin/channel fields to
`~/.openclaw/openclaw.json`, and stores the token in an owner-only file.
Unrelated OpenClaw configuration is preserved and a different existing Relay
identity is never overwritten.

The plugin follows OpenClaw's current channel SDK: setup discovery stays
network-free, installed packages load built JavaScript runtime entrypoints,
inbound events use stable ingress and envelope helpers, and replies use the
durable outbound path. Its present product scope is direct conversations and
text. Media is represented by a placeholder until Relay exposes agent
attachment downloads; reactions and receipts do not start agent turns.

## Pairing and credential boundary

Pairing is a device-code flow:

1. The CLI creates a short-lived pairing and long-polls it with a poll token.
2. Claiming creates a Relay agent owned by your account.
3. Relay returns that agent's Agent Token only to the waiting CLI.
4. The CLI stores the token with owner-only permissions and records the owner
   user id returned by `GET /v1/agents/me`.

Relay never receives your engine provider keys, SSH keys, or full parent
process environment. ACP subprocesses receive only platform basics,
engine/provider variables for the three supported engines, and variables you
explicitly add through `RELAYAPP_ENGINE_ENV`.

## Approval and delivery safety

* Only the pinned Relay owner can create prompts or answer approval cards by
  default. A non-owner message is dropped before its content is interpreted.
* Each approval is a durable create-once file. The exact operation must fit in
  the security preview; incomplete or oversized operations are denied.
* The event cursor advances atomically with the durable pending queue. A crash
  cannot acknowledge an event that was never recorded.
* Agent/tool turns are at-most-once. A durable attempt marker prevents a crash
  from silently repeating a deploy, deletion, command, or external send.
* Completed replies use a durable outbox and stable idempotency key, so delivery
  can retry without rerunning the agent turn.
* Event long-polling is exclusive per Agent Token and mutually exclusive with
  webhooks. Give every active consumer its own Relay agent/token.

## Diagnose

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

`doctor` verifies Node, pairing and owner pinning, token permissions, API
reachability, durable state, exact Claude/Codex adapter entrypoints, and the
installed Hermes binary/readiness check. A `401` is terminal and requires
re-pairing; it is never retried forever.

## Local files

```text theme={null}
~/.relayapp/config.json                   paired token, origin, owner (0600)
~/.relayapp/codex-notify.json             project roots opted into Codex notify
~/.relayapp/accounts/<identity>/state.json durable cursor, queue, outbox
~/.relayapp/accounts/<identity>/approvals/ one file per approval
~/.relayapp/accounts/<identity>/sessions.json conversation to ACP sessions
~/.relayapp/accounts/<identity>/mcp-sends/ durable Codex MCP logical sends
~/.relayapp/accounts/<identity>/installed-plugins/ stable plugin copies
```

## Next steps

* [Delivery model, including long polling](/guides/delivery-model)
* [Streaming replies](/guides/streaming)
* [Authentication](/authentication)