Relay SDK

One repo for building on Relay, the messenger for AI agents. It ships the relaymessenger npm tool (published as @relaymessenger/cli, name unchanged), the runtime integrations it bundles, the @relaymessenger/sdk contract and transport library, and forkable agent examples. Message Claude Code, Codex, or Hermes Agent from your phone, or run Relay as an OpenClaw channel: texts become engine turns, replies come back as messages, and tool approvals arrive as Allow/Deny cards you answer with a tap.

Docs: https://docs.relayapp.im

What's here

Path	What it is
packages/relaymessenger	The relaymessenger CLI (npm, @relaymessenger/cli): pair a machine with the Relay app via QR/code, drive Claude Code, Codex, or Hermes Agent over ACP, and install the bundled Codex, Claude Code, or OpenClaw integration.
packages/sdk	@relaymessenger/sdk: Relay contract types and transport (HTTPS client, Standard Webhooks verify, durable long-poll, idempotent sends). Not yet published to npm; its types will become generated from the Relay-Server schemas so the wire contract has one source of truth.
integrations/claude-code	Claude Code channel plugin (official Channels contract): push Relay messages into a running session, reply tool, phone permission relay. The npm CLI bundles and installs this plugin from a local marketplace; no GitHub checkout is required.
integrations/openclaw	OpenClaw channel plugin: an OpenClaw agent as a Relay contact (long-poll receive, durable chunked replies). The npm CLI bundles its installable archive.
integrations/vercel-ai	Vercel AI SDK webhook plugin (@relaymessenger/vercel-ai): verify signed Relay webhooks, then stream streamText(...) back as one canonical message.
examples	Forkable agents built on @relaymessenger/sdk (raw-webhook-agent, showcase-agent), plugin landing zones (examples/plugins), and smoke harnesses (examples/harnesses).

Quickstart

npm install -g @relaymessenger/cli
relaymessenger pair            # QR + code → claim in the Relay app
relaymessenger start --engine claude   # or codex | hermes

# Or install a native channel after pairing:
relaymessenger install-claude
relaymessenger install-openclaw

Full guide: https://docs.relayapp.im/guides/coding-agents

All four integration surfaces are release-gated together on Linux and Windows; the installed relaymessenger tarball and its Claude/Codex adapter runtime also run on macOS CI. @relaymessenger/sdk and the examples typecheck, build, and test inside the same npm run validate gate.

Claude Code plugin marketplace

This repository is also a Claude Code plugin marketplace: .claude-plugin/marketplace.json at the repo root lists the Relay channel plugin from integrations/claude-code. In Claude Code, run /plugin marketplace add relaymessenger/Relay-SDK to add it, then install the relay plugin from that marketplace.

npm release contracts

Only packages/relaymessenger is published by the automated npm release. Its tarball contains a strictly validated Claude Code marketplace and an installable OpenClaw plugin archive generated from the matching integration sources. The Claude Code and OpenClaw workspaces are bundled artifacts, not independent npm packages. integrations/vercel-ai is published separately as @relaymessenger/vercel-ai.

1. Update the CLI version and root lock metadata together:

   npm version X.Y.Z --workspace @relaymessenger/cli --no-git-tag-version
   npm run validate
   npm run pack:check

2. Merge that exact version change, then create and push an existing-commit tag named relaymessenger-vX.Y.Z. The version in packages/relaymessenger/package.json, the workspace entry in package-lock.json, and the tag must match exactly.

3. The tag starts .github/workflows/release-relaymessenger.yml. npm trusts that exact workflow through GitHub OIDC; no long-lived write token is allowed. If a tag run fails before terminal verification, rerun that original GitHub Actions run so npm provenance stays bound to the release tag and tag commit. The workflow deliberately has no manual-dispatch path: checking out an old tag from a default-branch dispatch would make GitHub's automatic provenance name the dispatch ref instead of the artifact's source tag. The workflow never creates a repository, changes repository visibility, or creates/pushes a tag.

4. CI reruns the full validation and package smokes, publishes only @relaymessenger/cli, strictly validates the source Claude plugin and marketplace, and proves the packed OpenClaw plugin through a real isolated gateway turn. The release job accepts only tags on reviewed main history, uses a GitHub-hosted runner, retains the exact .tgz with a source-SHA/digest manifest, publishes that file, and requires npm's registry integrity to match it. The public repository lets npm attach automatic provenance to the public package.

5. Before any retry, the workflow reconciles npm state. An already-published version is accepted only when its registry integrity matches the tagged source; publish is skipped and registry verification resumes. Finally, scripts/verify-relaymessenger-registry.mjs installs the exact registry version into a clean directory, loads the CLI, resolves both pinned ACP adapter runtimes, and verifies that both bundled native-integration artifacts are present.

@relaymessenger/vercel-ai follows the same contract through .github/workflows/release-vercel-ai.yml and tags named vercel-ai-vX.Y.Z. @relaymessenger/sdk follows it through .github/workflows/release-sdk.yml and tags named sdk-vX.Y.Z.

The repository is available under the MIT License; each integration documents its own trust, delivery, and crash-recovery boundary.