RX Claude Code Matrix Bridge
Live two-way Matrix ↔ Claude Code TUI bridge via the Channels API research preview.
Matrix messages appear inside your running Claude Code TUI as part of the conversation;
Claude's replies post back to the room. Survives claude --resume; falls back to
headless claude --print --resume when the TUI is offline so messages never get
lost.
Project page: https://arikw.github.io/claude-code-matrix-bridge/ — visual overview, feature tour, plugin comparison, screenshots.
| |
|---|
| Status | v0.4.24 — works against Claude Code 2.1.143; channels API still research preview |
| Platforms | Linux + macOS. Windows works via WSL2 only — hooks + bin/* are bash scripts that won't run under cmd/PowerShell. |
| Requires | Claude Code ≥ v2.1.80 (Channels API) · Node.js ≥ 20 · Matrix homeserver + bot account |
| Shell deps | bash, jq, curl, python3, plus standard POSIX awk / sed / tr / cat |
| License | MIT |
| Encryption | Plaintext only (E2EE on roadmap) |
Install the shell deps once if they aren't already present:
# Debian / Ubuntu / WSL
sudo apt-get install -y bash jq curl python3
# Alpine
apk add bash jq curl python3
# macOS (Homebrew)
brew install jq # bash, curl, python3 ship with macOS or via Xcode tools
Node.js: install whatever flow you prefer (nvm,
fnm, apt install nodejs, etc.) — must be
≥ 20 so dist/server.js runs under the ESM bundle.
⚠ THIS BRIDGE REQUIRES A LAUNCH FLAG. Claude Code must be started with
--dangerously-load-development-channels plugin:rx-claude-matrix-bridge@arikw
(see step 2). Without it, MCP tools work but matrix → TUI inbound is silently
dropped. The bridge detects the missing flag and surfaces a ⛓️💥 glyph in
the statusLine + a warning in /mx-link-chat output, but you'll still need to
relaunch Claude Code.
How it compares
A few Matrix-side plugins for Claude Code exist. Different trade-offs:
What this plugin wins on: multi-session routing (N rooms ↔ N TUI sessions), headless
fallback when the TUI is offline, the most complete setup wizard. What other plugins
have that this one doesn't: end-to-end encryption (elkimek, Kholtien), permission relay
via reactions (Kholtien), attachment / reaction / edit tools (nazbav).
All four use Claude Code as the chat-driven AI; the Channels-API-based ones
(this project, nazbav, Kholtien) need the --dangerously-load-development-channels
launch flag. The flag value must be plugin:<plugin-name>@<marketplace> (not
server:<mcp-server-name>) — CC's matcher splits the server-id on : and
rejects the server: form for plugin-loaded MCP servers. Without the correct
flag, inbound matrix events get silently dropped. The persistent setting
"channelsEnabled": true is additionally required on Team/Enterprise tiers
and on any account with a managed-settings policy file present; on a plain
personal account with no managed settings it's a no-op. This plugin's wizard
sets it defensively anyway and prints the shell-rc alias for the flag; the
others leave both as manual steps.
Full comparison + capability matrix on the project page.
Install
1. Get the plugin
Option A — Claude Code plugin marketplace (recommended for end users):
claude plugin marketplace add arikw/claude-code-matrix-bridge
claude plugin install rx-claude-matrix-bridge@arikw
This drops a pre-bundled copy under ~/.claude/plugins/.../rx-claude-matrix-bridge/.
No npm install needed — dist/server.js and dist/daemon.js are committed as
single-file esbuild bundles with all runtime deps inlined.
Option B — git clone (for development, or if you want to rebuild from source):
git clone https://github.com/arikw/claude-code-matrix-bridge.git
cd claude-code-matrix-bridge
npm install
npm run build # produces dist/server.js + dist/daemon.js
The runtime auto-detects: dist/server.js if present (production / built dev
checkout), otherwise spawns tsx server.ts directly (unbuilt dev checkout).
2. Launch Claude Code with the channels flag
