coderClaw

Matrix (plugin)

Matrix is an open, decentralized messaging protocol. CoderClaw connects as a Matrix user on any homeserver, so you need a Matrix account for the bot. Once it is logged in, you can DM the bot directly or invite it to rooms (Matrix “groups”). Beeper is a valid client option too, but it requires E2EE to be enabled.

Status: supported via plugin (@vector-im/matrix-bot-sdk). Direct messages, rooms, threads, media, reactions, polls (send + poll-start as text), location, and E2EE (with crypto support).

Plugin required

Matrix ships as a plugin and is not bundled with the core install.

Install via CLI (npm registry):

coderclaw plugins install @coderclaw/matrix

Local checkout (when running from a git repo):

coderclaw plugins install ./extensions/matrix

If you choose Matrix during configure/onboarding and a git checkout is detected, CoderClaw will offer the local install path automatically.

Details: Plugins

Setup

  1. Install the Matrix plugin:
    • From npm: coderclaw plugins install @coderclaw/matrix
    • From a local checkout: coderclaw plugins install ./extensions/matrix
  2. Create a Matrix account on a homeserver:
  3. Get an access token for the bot account:
    • Use the Matrix login API with curl at your home server:
    curl --request POST \
  --url https://matrix.example.org/_matrix/client/v3/login \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "m.login.password",
  "identifier": {
    "type": "m.id.user",
    "user": "your-user-name"
  },
  "password": "your-password"
}'
    • Replace matrix.example.org with your homeserver URL.
    • Or set channels.matrix.userId + channels.matrix.password: CoderClaw calls the same login endpoint, stores the access token in ~/.coderclaw/credentials/matrix/credentials.json, and reuses it on next start.
  4. Configure credentials:
    • Env: MATRIX_HOMESERVER, MATRIX_ACCESS_TOKEN (or MATRIX_USER_ID + MATRIX_PASSWORD)
    • Or config: channels.matrix.*
    • If both are set, config takes precedence.
    • With access token: user ID is fetched automatically via /whoami.
    • When set, channels.matrix.userId should be the full Matrix ID (example: @bot:example.org).
  5. Restart the gateway (or finish onboarding).
  6. Start a DM with the bot or invite it to a room from any Matrix client (Element, Beeper, etc.; see https://matrix.org/ecosystem/clients/). Beeper requires E2EE, so set channels.matrix.encryption: true and verify the device.

Minimal config (access token, user ID auto-fetched):

{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      accessToken: "syt_***",
      dm: { policy: "pairing" },
    },
  },
}

E2EE config (end to end encryption enabled):

{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      accessToken: "syt_***",
      encryption: true,
      dm: { policy: "pairing" },
    },
  },
}

Encryption (E2EE)

End-to-end encryption is supported via the Rust crypto SDK.

Enable with channels.matrix.encryption: true:

Crypto state is stored per account + access token in ~/.coderclaw/matrix/accounts/<account>/<homeserver>__<user>/<token-hash>/crypto/ (SQLite database). Sync state lives alongside it in bot-storage.json. If the access token (device) changes, a new store is created and the bot must be re-verified for encrypted rooms.

Device verification: When E2EE is enabled, the bot will request verification from your other sessions on startup. Open Element (or another client) and approve the verification request to establish trust. Once verified, the bot can decrypt messages in encrypted rooms.

Multi-account

Multi-account support: use channels.matrix.accounts with per-account credentials and optional name. See gateway/configuration for the shared pattern.

Each account runs as a separate Matrix user on any homeserver. Per-account config inherits from the top-level channels.matrix settings and can override any option (DM policy, groups, encryption, etc.).

{
  channels: {
    matrix: {
      enabled: true,
      dm: { policy: "pairing" },
      accounts: {
        assistant: {
          name: "Main assistant",
          homeserver: "https://matrix.example.org",
          accessToken: "syt_assistant_***",
          encryption: true,
        },
        alerts: {
          name: "Alerts bot",
          homeserver: "https://matrix.example.org",
          accessToken: "syt_alerts_***",
          dm: { policy: "allowlist", allowFrom: ["@admin:example.org"] },
        },
      },
    },
  },
}

Notes:

Routing model

Access control (DMs)

Rooms (groups)

{
  channels: {
    matrix: {
      groupPolicy: "allowlist",
      groups: {
        "!roomId:example.org": { allow: true },
        "#alias:example.org": { allow: true },
      },
      groupAllowFrom: ["@owner:example.org"],
    },
  },
}

Threads

Capabilities

Feature Status
Direct messages ✅ Supported
Rooms ✅ Supported
Threads ✅ Supported
Media ✅ Supported
E2EE ✅ Supported (crypto module required)
Reactions ✅ Supported (send/read via tools)
Polls ✅ Send supported; inbound poll starts are converted to text (responses/ends ignored)
Location ✅ Supported (geo URI; altitude ignored)
Native commands ✅ Supported

Troubleshooting

Run this ladder first:

coderclaw status
coderclaw gateway status
coderclaw logs --follow
coderclaw doctor
coderclaw channels status --probe

Then confirm DM pairing state if needed:

coderclaw pairing list matrix

Common failures:

For triage flow: /channels/troubleshooting.

Configuration reference (Matrix)

Full configuration: Configuration

Provider options:

This site is open source. Improve this page.