matrix

Claude Code Matrix Channel

Matrix channel plugin for Claude Code. Bridges Matrix room messages into an active Claude Code session via MCP, so you can chat with Claude from Element X, Cinny, FluffyChat, or any other Matrix client.

Port of the official Telegram channel plugin to Matrix Client-Server API.

How it works

Matrix user → Matrix client → Synapse/Conduit homeserver → [this plugin via /sync] → Claude Code session
                                                                                  ↕
Claude Code ← MCP Channel Protocol ← reply / edit / react / download_attachment tools

• Inbound: /_matrix/client/v3/sync long-poll (30s timeout) → notifications/claude/channel into the active CC session. State (next_batch) persisted in ~/.claude/channels/matrix/sync_token.txt so restarts don't replay history.
• Outbound: PUT /rooms/{roomId}/send/m.room.message/{txnId} for messages, m.replace relation for edits, m.reaction with m.annotation for reactions, two-step media upload for files.
• Access control: pairing codes, mxid allowlist, group chats with mention-only mode — state in ~/.claude/channels/matrix/access.json.
• Auto-join invites: DM invites or invites from allowlisted users auto-accept; non-DM invites from unknown users are declined.

Requirements

• Bun ≥ 1.0 (Node ≥ 18 should also work with a shebang swap)
• Claude Code ≥ 2.1.80
• Access to a Matrix homeserver where you control a bot account
• A bot access token (see setup below)
• Unencrypted rooms only — this plugin does NOT implement E2EE. Encrypted rooms will silently drop inbound.

Install

mkdir -p ~/.claude/plugins/marketplaces/local/plugins
cd ~/.claude/plugins/marketplaces/local/plugins
git clone https://github.com/nazbav/claude-code-matrix-channel.git matrix-channel

Create a minimal marketplace manifest at ~/.claude/plugins/marketplaces/local/.claude-plugin/marketplace.json:

{
  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
  "name": "local",
  "description": "Local Claude Code plugins",
  "owner": { "name": "you", "email": "[email protected]" },
  "plugins": [
    {
      "name": "matrix",
      "description": "Matrix channel for Claude Code",
      "category": "messaging",
      "source": "./plugins/matrix-channel",
      "author": { "name": "you" }
    }
  ]
}

claude plugin marketplace add ~/.claude/plugins/marketplaces/local
claude plugin install matrix@local

Create a bot account

On a Synapse + MAS setup:

# On the server: create the bot account
docker exec <mas-container> mas-cli -c /config/config.yaml manage register-user -y -p "<strong-random-password>" claude

# Get the access token via password login (from anywhere with HTTPS access to homeserver)
curl -X POST "https://matrix.example.org/_matrix/client/v3/login" \
  -H "Content-Type: application/json" \
  -d '{"type":"m.login.password","identifier":{"type":"m.id.user","user":"claude"},"password":"<pass>","device_id":"CLAUDE_CODE_BOT","initial_device_display_name":"Claude Code Bot"}'
# → {"access_token":"mct_xxx","device_id":"CLAUDE_CODE_BOT","user_id":"@claude:matrix.example.org"}

On a stock Synapse setup without MAS:

register_new_matrix_user -u claude -p '<pass>' -c /etc/matrix-synapse/homeserver.yaml http://localhost:8008
# Then log in via /login to get the access_token as above.

Drop the token into the channel .env:

mkdir -p ~/.claude/channels/matrix
cp ~/.claude/plugins/marketplaces/local/plugins/matrix-channel/.env.example \
   ~/.claude/channels/matrix/.env
$EDITOR ~/.claude/channels/matrix/.env   # fill in MATRIX_* values
chmod 600 ~/.claude/channels/matrix/.env

Run

Because local plugins aren't on Claude Code's approved-channels allowlist, launch with the dev flag:

claude --dangerously-load-development-channels plugin:matrix@local

Or alongside an allowlisted channel (e.g. Telegram):

claude --channels plugin:telegram@claude-plugins-official \
       --dangerously-load-development-channels plugin:matrix@local

Pair your Matrix account

1. From any Matrix client, start a DM with the bot (e.g. @claude:matrix.example.org).
2. Send any message. The bot replies with a 6-character pairing code.
3. In Claude Code, run:

/matrix:access pair <code>

After pairing, your DMs to the bot route straight into your Claude Code session as <channel source="matrix" chat_id="..." message_id="..." user="@you:server" ts="..."> notifications, and Claude's replies come back to the room via the reply tool.

Tools (what Claude can call)