Cc Matrix Channel

[](https://github.com/IA-PieroCV/ccmatrixchannel/actions/workflows/ci.yml) [](https://opensource.org/licenses/MIT)

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 
OR
/matrix:access pair 

/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:

1. Download binary from Releases
2. Save credentials to ~/.claude/channels/matrix/.env
3. Add to .mcp.json:

``json { "mcpServers": { "matrix": { "command": "/path/to/cc_matrix_channel" } } } ``

1. 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](LICENSE).

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: IA-PieroCV
• Source: IA-PieroCV/ccmatrix_channel
• License: MIT

Install and usage instructions live in the source repository linked above.