Chat with your live Claude Code session over Matrix. From your phone on the bus, a laptop at the café, a second machine at home, any device. Real-time, in the same conversation. Not a one-shot bot. Not a poll loop. Your actual running agent.
$ claude plugin marketplace add arikw/claude-code-matrix-bridge $ claude plugin install rx-claude-matrix-bridge@arikw $ claude --dangerously-load-development-channels plugin:rx-claude-matrix-bridge@arikw
Three pieces. Always-on daemon, per-session MCP relay, your matrix client.
A small Node.js daemon stays connected to your Matrix homeserver (Synapse, Tuwunel, Conduwuit, Dendrite, hosted matrix.org — anything spec-compliant). Auto-joins rooms you invite the bot to and forwards every message from the configured owner account.
An MCP server runs per Claude Code TUI. It registers your session with the daemon and binds it to a Matrix room via the /mx-link-chat slash command. Each room talks only to its bound session.
Matrix messages arrive in your TUI as Claude Code Channels-API notifications — part of the same conversation Claude is already having with you. Replies go back to Matrix via the reply tool.
When the TUI is offline, the daemon falls back to spawning claude --print --resume <sid> in headless mode — same path back to the room, no live session needed.
Not just for phones. For any time you're away from your terminal.
Phone, second machine, dev container, hotel laptop. Any device that runs a Matrix client can drive your live coding agent. No browser tab. No remote desktop. No SSH tunnel.
Messages arrive in the running Claude session as Channels-API notifications. Same conversation Claude was already having with you — your previous prompts, the project dir, everything in the session's context. Not a fresh process spawned per turn.
Closed your terminal? Headless claude --print --resume takes over so your message still gets answered. Re-opened with --resume? Routing reattaches. Plugin updated? Stale-version auto-detected.
Built for long coding sessions, not toy demos.
Matrix events wake your live TUI conversation instantly. Same agent, same context — no spawned subprocess, no key-injection.
N rooms <-> N TUI sessions. Each Matrix room talks only to its bound Claude Code session. Different projects stay isolated.
TUI offline? Daemon spawns claude --print --resume <sid> automatically. Replies post back to the room — when you re-open the TUI with --resume, the headless turn is already in the transcript.
Only messages from your configured matrix account drive Claude. Other room members are silently ignored. Single-user trust model.
First-run /mx-link-chat kicks off a guided wizard: homeserver detection, optional bot creation (Synapse admin only), one-shot password login to obtain an access token, config written to disk with chmod 0600.
Switched from TUI to phone mid-task? The bridge auto-prepends a recap instruction so Claude summarizes the other channel before answering. No black box.
Persistent indicator in your Claude Code statusLine. 🔗 mx:<room> when linked, ✏️ when the other side is typing, ⛓️💥 when the channels flag is missing, ⚙ when config is incomplete, 🔄 when the plugin was updated mid-session. Problems surface immediately — no silent failures.
Works with any matrix client + any matrix homeserver
Homeservers: Synapse · Tuwunel · Conduit · Conduwuit · Dendrite · self-hosted or hosted matrix.org. Use whatever you already trust.
A few Matrix-side plugins for Claude Code exist now. Different trade-offs. This one is the only one with built-in multi-session routing and a headless fallback when the TUI is offline — but other options have E2EE today, or a permission-relay UX, or attachment tools that this one doesn't.
| Capability |
rx-claude-matrix-bridge
(this project)
|
elkimek/matrix-bridge | nazbav/claude-code-matrix-channel | Kholtien/claude-connect-matrix-integration |
|---|---|---|---|---|
| Transport | Channels API push | MCP tool calls (pull) | Channels API push | Channels API push |
| Wakes live TUI session | yes | no — agent must call read_messages | yes | yes |
| Multi-session routing (N rooms → N sessions) | built-in | no | no | single-room (MATRIX_ROOM_ID) |
| Headless fallback when TUI offline | auto (spawns claude --print --resume) | no | no | no (but systemd + tmux scaffold) |
| Interactive setup wizard | yes (one-shot login + secrets write) | manual | partial (/matrix:access skill) | yes (/matrix:configure skill) |
| End-to-end encryption (E2EE) | roadmap | built-in (vodozemac) | no — encrypted rooms dropped | built-in (Rust Olm/Megolm) |
| Permission relay (approve Bash/Edit from matrix) | no | no | no | yes (👍/👎 reactions or text reply) |
| Attachments / reactions / edits | text only | text + send_and_wait | edit_message, react, download_attachment | reactions for permission UX |
| Owner-only access gate | yes (env-configured) | n/a (agent-controlled) | yes (pairing + allowlist) | yes (allowlist) |
Every plugin in the table above that uses Claude Code's Channels API push transport (rx-claude-matrix-bridge, nazbav/…matrix-channel, Kholtien/…matrix-integration) needs the launch flag --dangerously-load-development-channels plugin:<plugin-name>@<marketplace>. CC's matcher splits the MCP server-id on : and rejects the legacy server:<name> form for plugin-loaded servers (notifications silently dropped). The persistent setting "channelsEnabled": true in ~/.claude/settings.json is additionally required on Team/Enterprise tiers and on accounts with a managed-settings policy file; on plain personal accounts it's a no-op. elkimek/matrix-bridge avoids both because it doesn't use the Channels API at all — it exposes MCP tools the agent calls explicitly.
This plugin's wizard sets the setting and prints a tailored shell-rc alias for the flag so the user doesn't have to remember either. The other Channels-API plugins leave both as manual steps.
No. Any matrix homeserver works — matrix.org, your company's homeserver, or whatever a friend already runs. Self-hosting (Synapse, Tuwunel, Conduit, Conduwuit, Dendrite) gives you more control and is recommended long-term, but isn't required to get started.
The daemon spawns a headless claude --print --resume <sid> to handle the message, and posts the reply back to the matrix room. When you re-open the TUI with claude --resume, it sees the full transcript including that headless turn.
Only if you add them to the matrix room. The bridge routes per-room and per-session — you control sharing at the matrix-client layer. Invite, kick, leave, anytime.
Each Claude Code session links to its own room. The bridge can create one room per project (or you can pick existing rooms via an interactive picker). Inbound traffic in a room only ever reaches the session that owns it.
The Channels API is still a Claude Code research preview, and dangerously is Claude Code's convention for unstable / preview surfaces (same family as --dangerously-skip-permissions). If the API graduates to a stable name, the plugin will move with it.
Via WSL2 only. The plugin uses bash for hooks + the setup wizard. Native cmd.exe / PowerShell isn't supported and isn't planned.
Rooms are unencrypted by default in the current release — your matrix homeserver operator can read traffic. Use a homeserver you trust or self-host. E2EE (olm/megolm sidecar) is on the roadmap.