Matrix Channel for Claude Code
Chat with your running Claude Code session from any Matrix client.
Works with any Matrix homeserver (Continuwuity, Synapse, Conduit, Dendrite). Full E2EE support.
Features
- Two-way messaging with reply threading
- File attachments (send, receive, auto-decrypt E2EE media)
- Permission relay — approve/deny tool calls remotely
- Runtime config — change settings without restart
- Pairing-based access control
Setup (one-time)
Requires Bun.
/plugin marketplace add IA-PieroCV/cc_matrix_channel
/plugin install matrix@cc-matrix-channel
/reload-plugins
# You must need to restart your session to get the slash commands working and connect to the channel MCP
# claude --dangerously-load-development-channels plugin:matrix@cc-matrix-channel
/configure https://matrix.example.com @bot:example.com YOUR_PASSWORD
OR
/matrix:configure https://matrix.example.com @bot:example.com YOUR_PASSWORD
Then pair your account — DM the bot from your Matrix client:
/access pair <code>
OR
/matrix:access pair <code>
/access policy allowlist
OR
/matrix:access policy allowlist
Usage (every session)
claude --dangerously-load-development-channels plugin:matrix@cc-matrix-channel
Skills
| Skill | Description |
|---|---|
/matrix:access | Pairing, allowlists, groups, delivery settings |
/matrix:configure | Credentials, status, setup guide |
Tools
| Tool | Description |
|---|---|
reply | Send text + optional files, with threading |
react | Emoji reaction |
edit_message | Edit a sent message |
download_attachment | Download files (auto-decrypts E2EE) |
send_attachment | Send local files |
fetch_messages | Room history |
approve_pairing | Approve user access (terminal only) |
Configuration
Connection (~/.claude/channels/matrix/.env)
| Variable | Required | Description |
|---|---|---|
MATRIX_HOMESERVER_URL | Yes | Homeserver URL |
MATRIX_USER_ID | Yes | Bot user ID (@bot:server) |
MATRIX_PASSWORD | Yes* | Bot password (first-run only) |
MATRIX_STORE_PATH | No | E2EE key storage (default: ./data/matrix_store) |
MATRIX_ACCESS_TOKEN | No | Fallback auth (limited E2EE) |
MATRIX_DEVICE_ID | No | Device ID hint (auto-generated) |
MATRIX_STORE_PASSPHRASE | No | Encrypt store at rest |
Access & Delivery (~/.claude/channels/matrix/access.json)
Managed via /matrix:access. Changes take effect immediately.
| Setting | Default | Description |
|---|---|---|
dmPolicy | pairing | pairing, allowlist, or disabled |
allowFrom | [] | Allowed user IDs |
groups | {} | Per-room mention-only + patterns |
ackReaction | 👀 | Ack emoji (empty to disable) |
textChunkLimit | 4096 | Max chars per chunk |
chunkMode | newline | newline or length |
replyToMode | first | first, all, or off |
Manual Install
Without the plugin system:
- Download binary from Releases
- Save credentials to
~/.claude/channels/matrix/.env - Add to
.mcp.json:{ "mcpServers": { "matrix": { "command": "/path/to/cc_matrix_channel" } } } claude --dangerously-load-development-channels server:matrix
Build from Source
git clone https://github.com/IA-PieroCV/cc_matrix_channel
cd cc_matrix_channel
cargo build --release # Requires Rust 1.85+
Testing / Development
Test an RC build with --plugin-dir
The dev branch produces pre-release binaries. The Bun launcher downloads the exact version listed in plugin.json directly from GitHub Releases, so RC builds work the same as stable ones:
git clone https://github.com/IA-PieroCV/cc_matrix_channel
cd cc_matrix_channel
git checkout dev
# In your terminal:
claude --dangerously-load-development-channels --plugin-dir /path/to/cc_matrix_channel plugin:matrix@cc-matrix-channel
The launcher fetches the RC binary on first run and caches it.
Test local code changes (no GitHub release needed)
Build the binary and drop it in the launcher's cache path — the launcher skips the download when the file already exists:
cargo build --release
VERSION=$(grep '^version' .claude-plugin/plugin.json | sed 's/.*"\(.*\)".*/\1/')
cp target/release/cc_matrix_channel \
~/.claude/channels/matrix/plugin-data/bin/cc_matrix_channel-v${VERSION}
chmod +x ~/.claude/channels/matrix/plugin-data/bin/cc_matrix_channel-v${VERSION}
Then run with --plugin-dir as above. Repeat the cp after each cargo build.
Troubleshooting
| Problem | Fix |
|---|---|
| E2EE fails | Delete store directory, restart with password |
| "Cannot send to this room" | Send a message to the bot first |
| Bot ignores messages | Check /matrix:access or complete pairing |
| Session won't restore | Verify MATRIX_STORE_PATH |
Licensed under MIT.