# Add Matrix

Add Matrix channel integration via Chat SDK.

- Repository: https://github.com/nanocoai/nanoclaw (31069 stars)
- Category: Engineering
- License: MIT
- Last updated: 2026-10-30
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add nanocoai/nanoclaw --skill add-matrix -g -a claude-code -y`
Codex: `npx skills add nanocoai/nanoclaw --skill add-matrix -g -a codex -y`
Cursor: `npx skills add nanocoai/nanoclaw --skill add-matrix -g -a cursor -y`
Gemini CLI: `npx skills add nanocoai/nanoclaw --skill add-matrix -g -a gemini-cli -y`

## Description

Add Matrix channel integration via Chat SDK. Works with any Matrix homeserver.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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):

```nc:copy from-branch:channels
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:

```nc:append to:src/channels/index.ts
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:

```nc:copy
patches/@beeper__chat-adapter-matrix@0.2.0.patch
```

```nc:run effect:refresh
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:

```nc:dep
@beeper/chat-adapter-matrix@0.2.0
```

### 5. Verify and build

The rest: https://github.com/nanocoai/nanoclaw/blob/HEAD/.claude/skills/add-matrix/SKILL.md