Matrix Channel for NanoClaw

Add Matrix Channel

Adds Matrix support via the Chat SDK bridge. NanoClaw doesn't ship channels in trunk — this skill copies the Matrix adapter in from the channels branch.

The mechanical steps under Apply carry nc: directive fences: an agent reads the prose and applies them, and a parser can apply them deterministically from the same document. Every directive is idempotent, so the whole skill is safe to re-run; anything a parser can't apply falls back to the prose beside it.

Apply

1. Copy the adapter

Fetch the channels branch and copy the Matrix adapter into src/channels/ (overwrite — the branch is canonical):

src/channels/matrix.ts
src/channels/matrix-registration.test.ts

2. Register the adapter

Append the self-registration import to the channel barrel (skipped if the line is already present). This one line is the skill's only reach-in into core:

import './matrix.js';

3. Configure the ESM patch

The published adapter references matrix-js-sdk/lib/... without .js extensions, which fails under Node 22 strict ESM resolution. Register the committed pnpm patch before installing the package. pnpm reapplies it after every install and fails if the pinned package drifts away from the patch:

patches/@beeper__chat-adapter-matrix@0.2.0.patch

pnpm pkg set 'pnpm.patchedDependencies[@beeper/chat-adapter-matrix@0.2.0]=patches/@beeper__chat-adapter-matrix@0.2.0.patch'

4. Install the adapter package

Pinned to an exact version — the supply-chain policy rejects ranges and latest. The Matrix adapter lives in the @beeper/ namespace and versions on its own track (not the @chat-adapter/* family), so it carries its own pin:

@beeper/chat-adapter-matrix@0.2.0

5. Verify and build

Build guards the typed createChatSdkBridge(...) core call the adapter makes and fails if the import './matrix.js'; line is missing. The direct Node import checks the published ESM entrypoint using the real runtime resolver:

pnpm run build

node --input-type=module -e 'await import("@beeper/chat-adapter-matrix")'

pnpm exec vitest run src/channels/matrix-registration.test.ts

matrix-registration.test.ts imports the real channel barrel and asserts the registry contains matrix. It goes red if the import line is deleted or drifts, if the barrel fails to evaluate, or if @beeper/chat-adapter-matrix isn't installed (the import throws) — so it also covers the dependency from step 3.

End-to-end message delivery against a real Matrix homeserver is verified manually once the service is running — see Next Steps.

Credentials

The bot needs its own Matrix account — separate from the user's account. This is required because Matrix cannot send DMs to yourself. These steps are human and interactive (no parser can click through Element), so they stay prose.

Create a bot account

1. Open app.element.io in a private/incognito window (or sign out first)
2. Register a new account for the bot (e.g. andybot on matrix.org)
3. Note the bot's user ID (e.g. @andybot:matrix.org)

Choose an auth method

Option A: Username + Password (simpler)

No extra steps — just use the bot account's credentials directly. The adapter logs in automatically.

MATRIX_BASE_URL=https://matrix.org
MATRIX_USERNAME=andybot
MATRIX_PASSWORD=your-bot-password
MATRIX_USER_ID=@andybot:matrix.org
MATRIX_BOT_USERNAME=Andy

Option B: Access Token (recommended for production)

Get an access token from Element: sign into the bot account → Settings > Help & About > Access Token (under Advanced). Or via API:

curl -XPOST 'https://matrix.org/_matrix/client/r0/login' \
  -d '{"type":"m.login.password","user":"andybot","password":"..."}'

MATRIX_BASE_URL=https://matrix.org
MATRIX_ACCESS_TOKEN=your-access-token
MATRIX_USER_ID=@andybot:matrix.org
MATRIX_BOT_USERNAME=Andy

Optional settings

MATRIX_INVITE_AUTOJOIN=true                    # Auto-accept room invites (default: true)
MATRIX_INVITE_AUTOJOIN_ALLOWLIST=@you:matrix.org  # Only accept invites from these users
MATRIX_RECOVERY_KEY=your-recovery-key          # Enable E2EE cross-signing
MATRIX_DEVICE_ID=NANOCLAW01                    # Stable device ID across restarts

Store the credentials

Capture the values for the auth method you chose, then write them. prompt only asks and binds the answer to a name; a separate directive consumes it — so the same prompts could feed ncl or the OneCLI vault instead of .env by swapping only the consumer. The homeserver URL, the bot's user ID, and a display name are shared across both auth methods:

Paste the homeserver base URL, e.g. `https://matrix.org`.

Paste the bot's full Matrix user ID, e.g. `@andybot:matrix.org`.

Paste a display name for the bot, e.g. `Andy`.

MATRIX_BASE_URL={{base_url}}
MATRIX_USER_ID={{user_id}}
MATRIX_BOT_USERNAME={{bot_username}}

For Option A capture the bot login, for Option B capture the access token — set only the block matching your chosen method:

Option A only — the bot's login username (the localpart, e.g. `andybot`).

Option A only — the bot account's password.

MATRIX_USERNAME={{username}}
MATRIX_PASSWORD={{password}}

Option B only — the access token from Element Settings > Help & About, or from the login API.

MATRIX_ACCESS_TOKEN={{access_token}}