@mulmobridge/matrix
v0.1.1
Published
Matrix bridge for MulmoBridge — connect Matrix/Element to MulmoClaude
Readme
@mulmobridge/matrix
Experimental — please test and report issues.
Matrix bridge for MulmoClaude. Works with any Matrix homeserver (matrix.org, Element, Synapse, Dendrite, Conduit).
Setup
1. Create a bot account
Register a new user on your Matrix homeserver for the bot. On matrix.org:
# Using Element: create a new account manually
# Or use the admin API on your self-hosted server2. Get an access token
curl -X POST "https://matrix.org/_matrix/client/v3/login" \
-H "Content-Type: application/json" \
-d '{"type":"m.login.password","user":"@mulmo-bot:matrix.org","password":"..."}'
# → { "access_token": "syt_..." }3. Invite the bot to a room
In Element or your Matrix client, invite @mulmo-bot:matrix.org to the room where you want to use MulmoClaude.
4. Run the bridge
# Testing with mock server
npx @mulmobridge/mock-server &
MATRIX_HOMESERVER_URL=https://matrix.org \
MATRIX_ACCESS_TOKEN=syt_... \
MATRIX_USER_ID=@mulmo-bot:matrix.org \
MULMOCLAUDE_AUTH_TOKEN=mock-test-token \
npx @mulmobridge/matrix
# With real MulmoClaude
MATRIX_HOMESERVER_URL=https://matrix.org \
MATRIX_ACCESS_TOKEN=syt_... \
MATRIX_USER_ID=@mulmo-bot:matrix.org \
npx @mulmobridge/matrixEnvironment Variables
| Variable | Required | Description |
|---|---|---|
| MATRIX_HOMESERVER_URL | Yes | e.g. https://matrix.org |
| MATRIX_ACCESS_TOKEN | Yes | Bot user's access token |
| MATRIX_USER_ID | Yes | e.g. @mulmo-bot:matrix.org |
| MATRIX_ALLOWED_ROOMS | No | CSV of room IDs (empty = all joined rooms) |
| MULMOCLAUDE_API_URL | No | Default http://localhost:3001 |
| MULMOCLAUDE_AUTH_TOKEN | No | Bearer token |
| MATRIX_BRIDGE_DEFAULT_ROLE | No | Role id to seed new bridge sessions with (e.g. coder, general). Applied ONLY when a matrix session first appears — once the user switches role via /role <id> the session's own role wins. Unknown role ids silently fall back to the server's default with a warn log. |
| BRIDGE_DEFAULT_ROLE | No | Same as above but shared across every bridge. Transport-specific MATRIX_BRIDGE_DEFAULT_ROLE wins when both are set. |
Notes
- Matrix is an open, federated protocol. Your bot can join rooms on any server, not just the one it's registered on.
- No webhook or public URL needed — the bridge connects to the homeserver directly via long-polling sync.
- End-to-end encrypted rooms are not supported in this version (the SDK supports it, but key management adds complexity).
Ecosystem
Part of the @mulmobridge/* package family.
Shared libraries:
@mulmobridge/client— socket.io client library used by every bridge below@mulmobridge/protocol— wire types and constants@mulmobridge/chat-service— server-side relay + session store@mulmobridge/relay— Cloudflare Workers webhook proxy@mulmobridge/mock-server— mock server for local bridge development
Bridges (one npm package per platform):
@mulmobridge/bluesky— Bluesky DMs over atproto@mulmobridge/chatwork— Chatwork (Japanese business chat)@mulmobridge/cli— interactive terminal bridge@mulmobridge/discord— Discord bot via Gateway@mulmobridge/email— IMAP poll + SMTP reply, threading preserved@mulmobridge/google-chat— Google Chat via MulmoBridge relay@mulmobridge/irc— IRC (Libera, Freenode, custom)@mulmobridge/line— LINE Messaging API via MulmoBridge relay@mulmobridge/line-works— LINE Works (enterprise LINE)@mulmobridge/mastodon— Mastodon DMs + mentions@mulmobridge/matrix— Matrix / Element ← this package@mulmobridge/mattermost— Mattermost@mulmobridge/messenger— Facebook Messenger via MulmoBridge relay@mulmobridge/nostr— Nostr NIP-04 encrypted DMs@mulmobridge/rocketchat— Rocket.Chat@mulmobridge/signal— Signal via signal-cli-rest-api@mulmobridge/slack— Slack Socket Mode@mulmobridge/teams— Microsoft Teams via Bot Framework@mulmobridge/telegram— Telegram bot@mulmobridge/twilio-sms— SMS via Twilio Programmable Messaging@mulmobridge/viber— Viber Public Account bots@mulmobridge/webhook— generic HTTP webhook bridge@mulmobridge/whatsapp— WhatsApp Cloud API via MulmoBridge relay@mulmobridge/xmpp— XMPP / Jabber@mulmobridge/zulip— Zulip
License
MIT
