codebuddy-matrix-channel

Bridge Matrix chat to the Channel plugin (MCP server) for local CodeBuddy Code sessions.

Works the same as CodeBuddy's built-in Telegram / Discord / WeChat channels:

• Messages sent in a Matrix room appear in the CodeBuddy session as #matrix · @alice:matrix.org: 你好

• CodeBuddy's replies are sent back to the Matrix room via the reply tool

• Optional: forward CodeBuddy's permission request prompts to a “control room” to approve/deny tool calls from your phone

This plugin is based on CodeBuddy's Channel extension mechanism (see docs/cn/cli/channels.md and channels-reference.md) and does not require modifying CodeBuddy itself.

1. How it works

Matrix 房间  ──(matrix-js-sdk 收消息)──▶  matrix-channel (本插件)
                                              │  notifications/claude/channel
                                              ▼
                                        CodeBuddy Code 会话
                                              │  reply 工具 / 权限请求
                                              ▼
                                        matrix-channel ──(sendText)──▶ Matrix 房间

The plugin is started by CodeBuddy as a child process over stdio and communicates via the MCP protocol.

Related MCP server: mcacp

2. Installation

cd matrix-channel
npm install
npm run build        # 编译到 dist/（也可直接用 tsx 运行，无需构建）

Requires Node >= 20 at runtime.

2.1 Quick start (digital avatar)

1. Install / build

   cd matrix-channel && npm install && npm run build

2. Fill in .env (minimal usable set, see Section 3)

   MATRIX_HOMESERVER=https://im.yiq.pub
   MATRIX_ACCESS_TOKEN=<从 Element：设置 → 帮助 → 高级 → 访问令牌 复制>
   MATRIX_USER_ID=@evlon-ai:im.yiq.pub
   MATRIX_ALLOWLIST=@evlon:im.yiq.pub           # 防 prompt 注入，必填
   MATRIX_OWNER_ID=@evlon:im.yiq.pub            # 分身管理者=你，审批权只认此身份
   MATRIX_CONTROL_ROOM_ID=!<控制室房间ID>:im.yiq.pub
   MATRIX_MENTION_REQUIRED=true                 # 群里只响应 @分身
   # 可选：MATRIX_TRUSTED_SENDERS / MATRIX_TRUSTED_ROOMS / MATRIX_AUTHORIZED_WORK

3. Self-check (run this after every .env change)

   npm run doctor      # 期望：连接 ✅、账号 ✅、E2EE ✅

4. Connect to CodeBuddy: register in the project .mcp.json (absolute path), then start

   codebuddy --channels server:matrix --dangerously-load-development-channels

5. Daily use

   • @avatar in a group to assign work → trusted/authorized work runs automatically; unfamiliar work first produces a plan and goes to the control room to wait for your approve.

   • High-risk tools (Bash/write file, etc.) always go to the control room to ask you.

   • You issue commands in the control room (only MATRIX_OWNER_ID is recognized):

     • approve (run / go, optionally followed by a room ID) → authorize tasks in that room

     • yes <id> / no <id> → allow / deny pending high-risk permission requests

For encrypted rooms, set MATRIX_E2EE=true; if MATRIX_DEVICE_ID is left empty, it will be auto-selected from /devices; if an error occurs, fill in the device ID from “Settings → Devices”.

3. Configuration

Copy .env.example to .env and fill it in:

cp .env.example .env

⚠️ Security: be sure to configure MATRIX_ALLOWLIST (it checks by sender, not by room, to prevent any group member from injecting into the session). Leaving it empty allows everyone and is for local testing only.

4. Connecting to CodeBuddy

Method A: development period (bypassing the marketplace whitelist)

Register this plugin in your CodeBuddy project .mcp.json:

{
  "mcpServers": {
    "matrix": {
      "command": "npx",
      "args": ["tsx", "/绝对路径/matrix-channel/src/index.ts"]
    }
  }
}

Then start CodeBuddy:

codebuddy --channels server:matrix --dangerously-load-development-channels

After compiling, you can run it with node instead:

"args": ["node", "/绝对路径/matrix-channel/dist/index.js"]

Method B: package as a plugin (after submitting to the official marketplace)

npm run build

Then publish codebuddy-matrix-channel as a plugin, and afterwards use:

codebuddy --channels plugin:matrix-channel@<你的市场>

5. Usage

1. After startup, send a message in an allowed Matrix room, and #matrix · @你: ... will appear in the CodeBuddy session

2. When CodeBuddy finishes processing, the reply appears in the Matrix room

3. If MATRIX_CONTROL_ROOM_ID is configured: when CodeBuddy calls a tool that requires approval (Bash / Write, etc.), the control room receives a prompt (sent as an m.notice system message, which does not trigger unread/notifications); reply yes <id> to allow / no <id> to deny

reply tool parameters

For example, have CodeBuddy reply with an m.notice status message: reply({ chat_id: "!abc:server", text: "已处理", msgtype: "m.notice" }).

health_check tool

Can be called directly in the CodeBuddy session, or triggered in the /mcp health check; equivalent to the connectivity/E2EE part of npm run doctor, returning JSON:

{ "ok": true, "userId": "@alice:matrix.org", "e2ee": true, "cryptoReady": true }

When ok=false, an error field is included explaining the failure reason (connection/authentication/E2EE initialization).

6. Limitations and notes

• End-to-end encrypted (E2EE) rooms: by default, only unencrypted rooms are supported. To bridge encrypted rooms, set MATRIX_E2EE=true; the plugin reuses matrix-js-sdk's built-in Rust crypto (initRustCrypto), and the SDK automatically handles “decrypt on receive, encrypt on send” — no need to implement the encryption protocol yourself. When enabled:

  • Encrypted messages arrive as m.room.encrypted; after the SDK finishes decryption (Event.decrypted), the type changes to the real type, and the plugin then pushes it to the session;

  • Replies sent to encrypted rooms are automatically encrypted by the SDK;

  • Key storage (important, version-dependent): under matrix-js-sdk 42.x, the Rust crypto backend only has a wasm/IndexedDB implementation (@matrix-org/matrix-sdk-crypto-wasm), with no native Node backend. To make it run on Node, the plugin injects a global indexedDB shim into Node at startup using fake-indexeddb/auto — this shim is purely in-memory, so:

    • Keys actually exist only in process memory; MATRIX_CRYPTO_DB will not create a real SQLite file on disk in this version; after restarting the process, keys need to be re-negotiated (this does not affect sending/receiving, it just requires redoing key forwarding/device verification once).

    • True disk persistence requires upgrading to a matrix-js-sdk version that ships the native @matrix-org/matrix-sdk-crypto-nodejs backend, or a future version that supports the nodejs entry point (at that point, remove the fake-indexeddb shim and switch to the native backend).

    • Note: the already-installed @matrix-org/matrix-sdk-crypto-nodejs dependency is not called by the SDK in the current 42.2.0, and is only a fallback for future upgrades; the current encryption core works via wasm + the fake-indexeddb in-memory shim.

  • When a new device first enters an encrypted room, it is recommended to verify this bot's device in the Matrix client (otherwise the other party may see an “unverified device” warning, but messages will still send and receive normally).

• Media: by default, only message text is bridged into the session; enabling MATRIX_DOWNLOAD_MEDIA downloads images/files locally and injects them as [file: path] so the Agent can read them.

• Permission relay depends on CodeBuddy's claude/channel/permission capability; if the CodeBuddy version does not support it, the core chat bridge is unaffected.

7. Digital avatar: manager authorization model (core scenario)

Treat the avatar as a “colleague in the group”: anyone can @ it to assign work, yet it will not actually change anything until the manager approves.

Scenario

• Colleagues create multiple groups (e.g. #项目A, #客服), and there may be multiple avatar bots in a group at the same time. Colleagues @your avatar in the group to assign work; it only responds when @-mentioned (direct messages always respond).

• After receiving an assignment:

  • Common / authorized work (from your preset MATRIX_TRUSTED_SENDERS / MATRIX_TRUSTED_ROOMS, or within the scope described by MATRIX_AUTHORIZED_WORK) → runs automatically (safe tools).

  • Unfamiliar work (outside the authorized scope) → the avatar first produces a plan, calls request_approval to escalate to your control room; it only executes after you reply approve.

  • High-risk operations (MATRIX_HIGH_RISK_TOOLS, such as Bash / writing files) → regardless of source, always asks you first.

Architecture layers

• MCP plugin = secure transport + hard gate (enforced by code, not trusting the model): @ filtering and permission decisions allow/deny rely only on verifiable facts (whether it is the owner, whether it is a trusted source, whether it is a high-risk tool); control room approval only recognizes MATRIX_OWNER_ID.

• SKILL = policy brain (semantic judgment, delegated to the Agent): skills/matrix-avatar/SKILL.md guides the avatar to judge “common vs unfamiliar”; when unfamiliar, it enters plan mode and calls request_approval. The Agent only requests approval and never grants itself permission; approval comes only from “the manager's trusted source presets” or “the manager's approve”.

The plugin's built-in channel instructions already inline this policy, so it works without installing the SKILL separately; skills/matrix-avatar/SKILL.md is provided for you to reuse/tweak in CodeBuddy.

Three-tier task status (per room)

Control room commands (only valid for the manager MATRIX_OWNER_ID)

• approve (or run / go, optionally followed by a room ID, e.g. approve !projectA:server) → authorize the current task in that room, and the avatar starts executing.

• yes <id> / no <id> → allow / deny pending high-risk permission requests.

• Control room replies from anyone else are ignored.

Configuration example (.env)

MATRIX_OWNER_ID=@you:matrix.org
MATRIX_TRUSTED_SENDERS=@alice:matrix.org,@bob:matrix.org
MATRIX_TRUSTED_ROOMS=!projectA:server
MATRIX_AUTHORIZED_WORK=回答产品问题、总结会议纪要、起草文档
MATRIX_MENTION_REQUIRED=true
MATRIX_HIGH_RISK_TOOLS=Bash,Write,Edit,MultiEdit,NotebookEdit

8. Self-check (doctor)

After filling in .env, you can run the self-check first to confirm configuration, connectivity, and E2EE status before starting CodeBuddy:

npm run doctor

The self-check prints the current configuration (token masked), verifies that the homeserver is reachable and credentials are valid, and attempts to initialize Rust crypto when MATRIX_E2EE=true. Any failure gives a clear reason and exits with a non-zero exit code.

9. Directory structure

matrix-channel/
├── src/
│   ├── config.ts     # 环境变量 / 白名单 / 授权配置读取与校验
│   ├── matrix.ts     # Matrix 客户端封装（连接、@提及过滤、收/发、下载媒体、E2EE、自检）
│   ├── index.ts      # MCP 服务：channel 通知、授权硬闸、reply / request_approval 工具、控制室审批
│   └── doctor.ts     # `npm run doctor` 自检入口
├── skills/
│   └── matrix-avatar/
│       └── SKILL.md  # 分身行为策略（语义判断：常用 vs 陌生）
├── package.json
├── tsconfig.json
├── .gitignore
├── .env.example
└── README.md