elizaos--eliza/plugins/plugin-matrix/AGENTS.md

@elizaos/plugin-matrix

Matrix messaging connector for Eliza agents — connects agents to Matrix homeservers via matrix-js-sdk.

Purpose / role

Adds Matrix protocol support to an Eliza agent: receive and send messages in Matrix rooms, manage room membership, send reactions, threading, typing indicators, and read receipts. Auto-enabled when a matrix connector block is present in the agent config (config.connectors.matrix.enabled !== false). Node.js only (see eliza.platforms in package.json).

Plugin surface

The exported matrixPlugin object (src/index.ts) registers:

Kind	Name	What it does
Service	MatrixService (serviceType: "matrix")	Core Matrix client lifecycle: connects to homeserver, syncs rooms, dispatches incoming messages as events, exposes send/react/join/leave/typing/read-receipt API. Registers a MessageConnector with the runtime that wires resolveTargets, listRecentTargets, listRooms, fetchMessages, searchMessages, reactHandler, joinHandler, leaveHandler, getChatContext, getUserContext, and the sendHandler.
Service	MatrixWorkflowCredentialProvider (serviceType: "workflow_credential_provider")	Supplies matrixApi credentials (accessToken + homeserverUrl) to the workflow plugin without adding a compile-time dep on it.
Actions	(none registered)	Matrix send/react/join/leave surfaces are exposed via the MessageConnector registered by MatrixService, not through standalone actions.
Providers	(none registered)	Room list is exposed through the connector's MESSAGE list_channels path; provider index is intentionally empty.

On init, the plugin also registers a ConnectorAccountProvider with the ConnectorAccountManager (via createMatrixConnectorAccountProvider).

Events emitted

Emitted on runtime.emitEvent:

Event constant	Value	Trigger
MatrixEventTypes.MESSAGE_RECEIVED	MATRIX_MESSAGE_RECEIVED	Incoming m.room.message (text only; filtered by requireMention if set)
MatrixEventTypes.MESSAGE_SENT	MATRIX_MESSAGE_SENT	Message sent via sendMessage
MatrixEventTypes.ROOM_JOINED	MATRIX_ROOM_JOINED	joinRoom succeeds
MatrixEventTypes.ROOM_LEFT	MATRIX_ROOM_LEFT	leaveRoom succeeds
MatrixEventTypes.SYNC_COMPLETE	MATRIX_SYNC_COMPLETE	Matrix PREPARED sync state

Layout

plugins/plugin-matrix/
  auto-enable.ts                      Auto-enable check (loaded by elizaOS boot engine)
  src/
    index.ts                          Plugin definition — services list, init, dispose
    service.ts                        MatrixService — SDK client lifecycle, send/react/join/leave,
                                        MessageConnector registration, multi-account dispatch
    accounts.ts                       Multi-account config resolution (env vars + character settings
                                        + MATRIX_ACCOUNTS JSON); exports resolveMatrixAccountSettings,
                                        listMatrixAccountIds, normalizeMatrixAccountId, readMatrixAccountId
    connector-account-provider.ts     ConnectorAccountProvider adapter for ConnectorAccountManager
    workflow-credential-provider.ts   MatrixWorkflowCredentialProvider — duck-typed for plugin-workflow
    types.ts                          MatrixSettings, MatrixMessage, MatrixRoom, IMatrixService,
                                        MatrixEventTypes enum, error classes, utility functions
    fake-indexeddb-auto.d.ts          Type shim for fake-indexeddb used in tests
    providers/
      index.ts                        Empty; rooms exposed through MessageConnector, not providers
    __tests__/
      accounts.test.ts                Account config resolution unit tests
      connector.test.ts               Connector integration tests
      crypto-store.test.ts            Crypto store tests
      service-hardening.test.ts       MatrixService hardening / error-path tests
      workflow-credential-provider.test.ts  WorkflowCredentialProvider unit tests

Commands

All scripts are relative to the plugin root:

bun run --cwd plugins/plugin-matrix build         # Compile via build.ts → dist/
bun run --cwd plugins/plugin-matrix test          # vitest run
bun run --cwd plugins/plugin-matrix lint          # Biome check + fix
bun run --cwd plugins/plugin-matrix lint:check    # Biome check (read-only)
bun run --cwd plugins/plugin-matrix format        # Biome format + fix
bun run --cwd plugins/plugin-matrix format:check  # Biome format (read-only)
bun run --cwd plugins/plugin-matrix typecheck     # tsgo --noEmit

Config / env vars

Settings are resolved in priority order: per-account object in MATRIX_ACCOUNTS JSON > character.settings.matrix.<field> > env var (env vars only apply to the default account).

Env var	Required	Description
MATRIX_ACCESS_TOKEN	Yes	Access token for the Matrix bot account
MATRIX_HOMESERVER	Yes (validated at init)	Homeserver URL, e.g. https://matrix.org
MATRIX_USER_ID	Yes (validated at init)	Full Matrix user ID, e.g. @bot:matrix.org
MATRIX_PASSWORD	No	Password for password-based login (alternative to access token)
MATRIX_DEVICE_ID	No	Device ID for this session (auto-assigned if absent)
MATRIX_ROOMS	No	Comma-separated room IDs / aliases to auto-join on start
MATRIX_AUTO_JOIN	No (false)	Auto-accept room invites
MATRIX_ENCRYPTION	No (false)	Enable E2EE (requires SDK support)
MATRIX_REQUIRE_MENTION	No (false)	Only process messages that mention the bot
MATRIX_VERIFY_ALLOWLIST	No	Allowlist of user IDs / devices permitted for verification
MATRIX_PERSONAL	No	Enable personal mode (single-user, non-bot usage)
MATRIX_ACCOUNTS	No	JSON array/object of per-account configs for multi-account setups
MATRIX_DEFAULT_ACCOUNT_ID	No	Which account is the default when multiple are configured
MATRIX_ACCOUNT_ID	No	Alias for MATRIX_DEFAULT_ACCOUNT_ID

Character-level config (character.settings.matrix) accepts the same fields as MatrixSettings (see src/types.ts). Multi-account: set character.settings.matrix.accounts as a keyed object, or supply MATRIX_ACCOUNTS as a JSON array with an accountId/id field per entry.

How to extend

Add a new action:

1. Create src/actions/<name>.ts exporting an Action conforming to @elizaos/core.
2. Import and push it into the actions: [] array in src/index.ts.

Add a new provider:

1. Create src/providers/<name>.ts exporting a Provider.
2. Import and push into the providers: [] array in src/index.ts.

Add a new event handler: Inside MatrixService.setupEventHandlers in src/service.ts, call state.client.on(...) for the desired Matrix SDK event, then emit via this.runtime.emitEvent(MatrixEventTypes.<NAME>, payload). Add the new event constant to the MatrixEventTypes enum in src/types.ts.

Add a second Matrix account: Supply MATRIX_ACCOUNTS='[{"accountId":"work","homeserver":"...","userId":"...","accessToken":"..."}]' or add an accounts key to character.settings.matrix. MatrixService.initialize iterates listMatrixAccountIds and creates a separate SDK client + MessageConnector registration per account.

Conventions / gotchas

• Node.js only. matrix-js-sdk is a Node.js package; this plugin will not work in browser or mobile runtimes.
• Auto-enable module is imported at boot before full plugin init. Keep auto-enable.ts free of transitive imports from src/.
• No actions array. Matrix send/react/join/leave are exposed via the runtime's MessageConnector abstraction, not via Plugin.actions. Other plugins invoke Matrix through the connector system (source: "matrix").
• E2EE flag exists but relies on SDK-level support. Setting MATRIX_ENCRYPTION=true flags the intent; the SDK must also have appropriate crypto support enabled in the deployment.
• Message splitting is the caller's responsibility. MAX_MATRIX_MESSAGE_LENGTH = 4000 (exported from types.ts) — the service does not auto-split; callers must chunk before calling sendMessage.
• providers/index.ts is intentionally empty. Room context is surfaced by the MessageConnector hooks (getChatContext, listRooms), not by a runtime provider.
• MatrixWorkflowCredentialProvider duck-types the workflow contract. It does not import @elizaos/plugin-workflow to avoid a circular dep; the runtime matches by serviceType string only.

⛔ NON-NEGOTIABLE — evidence, trajectories & real end-to-end tests

The binding, repo-wide standard is AGENTS.md. Read it. Nothing in this package is done until it is proven done — a reviewer must confirm it works without reading the code, from the artifacts you attach. This applies to every feature, fix, refactor, and chore here. "Tests pass" is not proof; "CI is green" is not proof.

• Record AND read model trajectories. Capture the actual inputs and outputs of the model from a live LLM — not the deterministic proxy, not a mock: the prompt, the providers/context, the raw model output, every tool/action call, and the result. Then open the trajectory and review it by hand. A captured-but-unread trajectory is not evidence (packages/scenario-runner/bin/eliza-scenarios run <scenario> --report <out>).
• Real, full-featured E2E — no larp. Every feature ships detailed end-to-end tests that drive the real path end to end. Not the happy "front door" only: cover error paths, edge/empty/invalid input, concurrency, roles/permissions, and adversarial input. A test that asserts against a mock/stub/fixture standing in for the thing under test does not count. If the real model/device/chain/connector/account is hard to reach, make it reachable — that is the work, not an excuse to mock. If the existing tests here are shallow or mocked, fixing them is part of your change.
• Screenshots + logs at every phase, plus a complete walkthrough video/run-through of the entire feature or view, start to finish (bun run test:e2e:record).
• Manually review every artifact the change touches — never just the green check: client logs (console + network), server logs ([ClassName] …), the model trajectories in and out, before/after full-page screenshots, and the domain artifacts listed below for this package.
• No residuals. No shortcuts. The goal is not "done" — it is everything done. Clear every blocker by the hard path: build the real architecture, stand up the real model/device/service, actually test it. Never leave a TODO, a stub, a stepping-stone, or a "follow-up." When unsure, research thoroughly, weigh the options, and ship the best, highest-effort, production-ready version. Keep going until every possibility is exhausted.

Artifacts → attached inline in the PR (MP4 video, JPG screenshots, logs in <details>); attach each evidence type or explicitly mark it N/A with a reason — never leave it blank. If develop moved and changed behavior, re-capture evidence; stale proof is worse than none.

Capture & manually review for this package — platform connector:

• A real (or sandbox-account) round-trip on the platform: inbound message → agent → outbound reply, captured as logs and a screenshot/recording of the actual conversation.
• The raw inbound event/webhook payload and the outbound API request/response, with IDs mapped correctly (stringToUuid / createUniqueUuid).
• Attachments, threads/replies, edits, multi-account, and rate-limit/error paths — not just a single text ping.
• The agent trajectory for the turn the connector drove.