matrix

Matrix Channel for Claude Code

A channel plugin that lets you message Claude Code from Element (or any Matrix client) with end-to-end encryption.

Features

• E2E Encryption — persistent Rust-based crypto via matrix-bot-sdk + @matrix-org/matrix-sdk-crypto-nodejs (SQLite storage)
• Access Control — allowlist, pairing codes, per-room group policies
• Group Rooms — optional mention-to-activate (requireMention)
• Attachments — images download inline, files via download_attachment tool
• Message Editing — edit previous bot messages
• Reactions — emoji reactions on messages
• Permission Requests — approve/deny tool permissions from Element
• Skills — /matrix:access and /matrix:configure for setup and management

Prerequisites

• Bun runtime
• A Matrix homeserver (e.g., Synapse) with a bot account
• Claude Code with plugin support

Setup

1. Create a bot account on your Matrix homeserver

Register a user (e.g., @claude:your-server.com) and get an access token.

2. Install the plugin

# Clone to your local plugins directory
mkdir -p ~/.claude/plugins/local
git clone https://github.com/Dave700r/claude-code-matrix-channel.git ~/.claude/plugins/local/matrix
cd ~/.claude/plugins/local/matrix
bun install

3. Configure credentials

Create ~/.claude/channels/matrix/.env:

MATRIX_HOMESERVER=https://matrix.your-server.com
MATRIX_USER_ID=@claude:your-server.com
MATRIX_ACCESS_TOKEN=syt_your_token_here
MATRIX_DEVICE_ID=YOUR_DEVICE_ID

chmod 600 ~/.claude/channels/matrix/.env

Or use the skill: /matrix:configure <homeserver> <user_id> <access_token> [device_id]

4. Register the local marketplace

Create ~/.claude/plugins/local/.claude-plugin/marketplace.json:

{
  "name": "local",
  "description": "Local plugins",
  "owner": {
    "name": "Your Name",
    "email": "you@example.com"
  },
  "plugins": [
    {
      "name": "matrix",
      "description": "Matrix channel for Claude Code",
      "category": "productivity",
      "source": "./matrix"
    }
  ]
}

Add to ~/.claude/settings.json:

{
  "enabledPlugins": {
    "matrix@local": true
  },
  "extraKnownMarketplaces": {
    "local": {
      "source": {
        "source": "directory",
        "path": "~/.claude/plugins/local"
      }
    }
  }
}

5. Add yourself to the allowlist

# In Claude Code:
/matrix:access allow @you:your-server.com

6. Launch with channels

claude --dangerously-load-development-channels plugin:matrix@local --permission-mode bypassPermissions

For a persistent background session:

screen -dmS claude-matrix claude --dangerously-load-development-channels plugin:matrix@local --permission-mode bypassPermissions

Skills

• /matrix:configure — Set up credentials, check status, review access policy
• /matrix:access — Manage pairing, allowlist, DM/group policy, delivery settings

Tools

Tool	Description
reply	Send a message to a Matrix room
react	Add an emoji reaction
edit_message	Edit a previously sent message
download_attachment	Download a file from a Matrix message

Access Control

All access state lives in ~/.claude/channels/matrix/access.json:

• dmPolicy: allowlist (default), pairing, or disabled
• allowFrom: Array of allowed Matrix user IDs
• groups: Per-room policies with optional requireMention and allowFrom
• ackReaction: Emoji to react with on received messages (e.g., "👀")

Technical Details

• Uses RustSdkCryptoStorageProvider with SQLite for persistent E2E keys
• Crypto store persists across restarts — no re-verification needed
• Runs via Bun (same runtime as the official Telegram plugin)
• Tokio runtime panics on abrupt shutdown are harmless (Rust crypto cleanup)

License

Apache-2.0